From 54071473fce9ed60be7dc7c8ec34e33d4535800d Mon Sep 17 00:00:00 2001 From: catlog22 Date: Thu, 19 Mar 2026 15:17:48 +0800 Subject: [PATCH] Refactor team edict agent and task schemas; remove deprecated files - Deleted Zhongshu Planner agent documentation as it is no longer needed. - Removed agent instruction documentation to streamline task assignment process. - Eliminated tasks schema file to simplify task management. - Updated Codex Lens installation instructions to use 'uv' for pip commands. - Bumped version to 0.4.1 in pyproject.toml and adjusted dependencies. - Enhanced API embedding with text truncation and automatic batch splitting on 413 errors. - Improved indexing pipeline with metadata registration and progress reporting. - Converted index_project and index_update functions to async for better performance. --- .../commands/workflow/analyze-with-file.md | 94 ++- .claude/skills/team-edict/SKILL.md | 204 ----- .../skills/team-edict/role-specs/bingbu.md | 56 -- .../skills/team-edict/role-specs/gongbu.md | 86 -- .claude/skills/team-edict/role-specs/hubu.md | 57 -- .../skills/team-edict/role-specs/libu-hr.md | 64 -- .claude/skills/team-edict/role-specs/libu.md | 56 -- .../skills/team-edict/role-specs/menxia.md | 139 ---- .../skills/team-edict/role-specs/shangshu.md | 105 --- .../skills/team-edict/role-specs/xingbu.md | 85 -- .../skills/team-edict/role-specs/zhongshu.md | 116 --- .../team-edict/roles/coordinator/role.md | 254 ------ .../skills/team-edict/specs/quality-gates.md | 133 --- .../skills/team-edict/specs/team-config.json | 180 ---- .claude/skills/workflow-lite-execute/SKILL.md | 63 +- .claude/skills/workflow-lite-plan/SKILL.md | 59 +- .../skills/workflow-lite-test-review/SKILL.md | 358 +++----- .codex/skills/team-edict/SKILL.md | 781 ------------------ .codex/skills/team-edict/agents/aggregator.md | 246 ------ .../team-edict/agents/menxia-reviewer.md | 229 ----- .../skills/team-edict/agents/qa-verifier.md | 274 ------ .../team-edict/agents/shangshu-dispatcher.md | 247 ------ .../team-edict/agents/zhongshu-planner.md | 198 ----- .../instructions/agent-instruction.md | 177 ---- .../skills/team-edict/schemas/tasks-schema.md | 163 ---- codex-lens-v2/README.md | 12 +- codex-lens-v2/pyproject.toml | 2 +- codex-lens-v2/src/codexlens_search/bridge.py | 2 + codex-lens-v2/src/codexlens_search/config.py | 5 +- .../src/codexlens_search/embed/api.py | 35 +- .../src/codexlens_search/indexing/pipeline.py | 187 ++++- .../src/codexlens_search/mcp_server.py | 49 +- 32 files changed, 511 insertions(+), 4205 deletions(-) delete mode 100644 .claude/skills/team-edict/SKILL.md delete mode 100644 .claude/skills/team-edict/role-specs/bingbu.md delete mode 100644 .claude/skills/team-edict/role-specs/gongbu.md delete mode 100644 .claude/skills/team-edict/role-specs/hubu.md delete mode 100644 .claude/skills/team-edict/role-specs/libu-hr.md delete mode 100644 .claude/skills/team-edict/role-specs/libu.md delete mode 100644 .claude/skills/team-edict/role-specs/menxia.md delete mode 100644 .claude/skills/team-edict/role-specs/shangshu.md delete mode 100644 .claude/skills/team-edict/role-specs/xingbu.md delete mode 100644 .claude/skills/team-edict/role-specs/zhongshu.md delete mode 100644 .claude/skills/team-edict/roles/coordinator/role.md delete mode 100644 .claude/skills/team-edict/specs/quality-gates.md delete mode 100644 .claude/skills/team-edict/specs/team-config.json delete mode 100644 .codex/skills/team-edict/SKILL.md delete mode 100644 .codex/skills/team-edict/agents/aggregator.md delete mode 100644 .codex/skills/team-edict/agents/menxia-reviewer.md delete mode 100644 .codex/skills/team-edict/agents/qa-verifier.md delete mode 100644 .codex/skills/team-edict/agents/shangshu-dispatcher.md delete mode 100644 .codex/skills/team-edict/agents/zhongshu-planner.md delete mode 100644 .codex/skills/team-edict/instructions/agent-instruction.md delete mode 100644 .codex/skills/team-edict/schemas/tasks-schema.md diff --git a/.claude/commands/workflow/analyze-with-file.md b/.claude/commands/workflow/analyze-with-file.md index 71e7cceb..8e19d73c 100644 --- a/.claude/commands/workflow/analyze-with-file.md +++ b/.claude/commands/workflow/analyze-with-file.md @@ -405,14 +405,89 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} **Handle user selection**: - **"执行任务"** -> MUST invoke Skill tool (do NOT just display a summary and stop): - 1. Build `taskDescription` from high/medium priority recommendations (fallback: summary) - 2. Assemble context: `## Prior Analysis ({sessionId})` + summary + key files (up to 8) + key findings (up to 5) from exploration-codebase.json - 3. **Invoke Skill tool immediately**: - ```javascript - Skill({ skill: "workflow-lite-plan", args: `${taskDescription}\n\n${contextLines}` }) - ``` - If Skill invocation is omitted, the workflow is BROKEN. + **"执行任务"** -> Implementation Scoping + Skill invocation (MUST NOT just display summary and stop): + + **Step A: Build Implementation Scope** — Transform recommendations into actionable specs: + ```javascript + // Filter to accepted/modified recommendations only + const actionableRecs = conclusions.recommendations + .filter(r => r.review_status === 'accepted' || r.review_status === 'modified') + .sort((a, b) => (a.priority === 'high' ? 0 : 1) - (b.priority === 'high' ? 0 : 1)) + + // Map each recommendation to implementation scope using code_anchors + const implScope = actionableRecs.map(rec => ({ + objective: rec.action, // WHAT to do + rationale: rec.rationale, // WHY + priority: rec.priority, + target_files: rec.steps.flatMap(s => s.target ? [s.target] : []) + .concat((conclusions.code_anchors || []) + .filter(a => rec.action.includes(a.significance) || rec.steps.some(s => s.description.includes(a.file))) + .map(a => ({ path: a.file, lines: a.lines, context: a.significance }))), + acceptance_criteria: rec.steps.map(s => s.verification || s.description), + change_summary: rec.steps.map(s => `${s.target || 'TBD'}: ${s.description}`).join('; ') + })) + ``` + + **Step B: User Scope Confirmation** (skip in auto mode): + ```javascript + // Present implementation scope for confirmation + console.log(`## Implementation Scope (${implScope.length} items)`) + implScope.forEach((item, i) => { + console.log(`${i+1}. **${item.objective}** [${item.priority}]`) + console.log(` Files: ${item.target_files.map(f => typeof f === 'string' ? f : f.path).join(', ') || 'TBD by lite-plan'}`) + console.log(` Done when: ${item.acceptance_criteria.join(' + ')}`) + }) + + if (!autoMode) { + AskUserQuestion({ + questions: [{ + question: "Implementation scope correct? lite-plan will break these into concrete tasks.", + header: "Scope确认", + multiSelect: false, + options: [ + { label: "确认执行", description: "Scope is clear, proceed to planning" }, + { label: "调整范围", description: "Narrow or expand scope before planning" }, + { label: "补充标准", description: "Add/refine acceptance criteria" } + ] + }] + }) + // Handle "调整范围" / "补充标准" -> update implScope, re-confirm + } + ``` + + **Step C: Build Structured Handoff & Invoke Skill**: + ```javascript + // Structured handoff — lite-plan parses this as JSON block, not free text + const handoff = { + source: 'analyze-with-file', + session_id: sessionId, + session_folder: sessionFolder, + summary: conclusions.summary, + implementation_scope: implScope, // WHAT + acceptance criteria + code_anchors: (conclusions.code_anchors || []).slice(0, 10), // WHERE + key_files: explorationResults.relevant_files?.slice(0, 8) || [], + key_findings: conclusions.key_conclusions?.slice(0, 5) || [], + decision_context: conclusions.decision_trail?.slice(-3) || [] // recent decisions for context + } + + const handoffBlock = `## Prior Analysis (${sessionId}) + +\`\`\`json:handoff-spec +${JSON.stringify(handoff, null, 2)} +\`\`\` + +### Summary +${conclusions.summary} + +### Implementation Scope +${implScope.map((item, i) => `${i+1}. **${item.objective}** [${item.priority}] + - Files: ${item.target_files.map(f => typeof f === 'string' ? f : f.path).join(', ') || 'TBD'} + - Done when: ${item.acceptance_criteria.join('; ')} + - Changes: ${item.change_summary}`).join('\n')}` + + Skill({ skill: "workflow-lite-plan", args: handoffBlock }) + ``` + If Skill invocation is omitted, the workflow is BROKEN. 4. After Skill invocation, analyze-with-file is complete — do not output any additional content **"产出Issue"** -> Convert recommendations to issues: @@ -430,6 +505,7 @@ CONSTRAINTS: Focus on ${dimensions.join(', ')} - `key_conclusions[]`: {point, evidence, confidence, code_anchor_refs[]} - `code_anchors[]`: {file, lines, snippet, significance} - `recommendations[]`: {action, rationale, priority, steps[]: {description, target, verification}, review_status: accepted|modified|rejected|pending} +- `implementation_scope[]`: {objective, rationale, priority, target_files[], acceptance_criteria[], change_summary} — built in Phase 4 "执行任务" Step A, only for accepted/modified recommendations - `open_questions[]`, `follow_up_suggestions[]`: {type, summary} - `decision_trail[]`: {round, decision, context, options_considered, chosen, rejected_reasons, reason, impact} - `narrative_trail[]`: {round, starting_point, key_progress, hypothesis_impact, updated_understanding, remaining_questions} @@ -521,7 +597,7 @@ Present 2-3 top directions per dimension, allow multi-select + custom. -> **Lite-plan handoff**: Phase 4「执行任务」assembles analysis context as inline `## Prior Analysis` block, allowing lite-plan to skip redundant exploration. +> **Lite-plan handoff**: Phase 4「执行任务」builds structured `handoff-spec` JSON (implementation_scope with acceptance_criteria, code_anchors, key_findings) embedded in `## Prior Analysis` block. lite-plan parses `json:handoff-spec` to directly map scope items → tasks, skipping exploration and using acceptance_criteria as convergence.criteria. --- diff --git a/.claude/skills/team-edict/SKILL.md b/.claude/skills/team-edict/SKILL.md deleted file mode 100644 index 05dcdeb7..00000000 --- a/.claude/skills/team-edict/SKILL.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -name: team-edict -description: | - 三省六部 multi-agent 协作框架，完整复刻 Edict 架构。 - 太子接旨 -> 中书省规划 -> 门下省审议(多CLI并行) -> 尚书省调度 -> 六部并行执行。 - 强制看板状态上报（state/flow/progress），支持 Blocked 一等公民状态，全流程可观测。 - Triggers on "team edict", "三省六部", "edict team". -allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*) ---- - -# Team Edict — 三省六部 - -受古代三省六部制启发的多 agent 协作框架。核心设计：**严格的级联审批流 + 实时看板可观测性 + 多 CLI 并行分析**。 - -## Architecture - -``` -+----------------------------------------------------------+ -| Skill(skill="team-edict") | -| args="任务描述" | -+------------------------+---------------------------------+ - | - Coordinator (太子·接旨分拣) - Phase 0-5 orchestration - | - +---------------+--------------+ - | | - [串行审批链] [看板 State Bus] - | | - 中书省(PLAN) ← 所有 agent 强制上报 - | state/flow/progress - 门下省(REVIEW) ← 多CLI审议 - | - 尚书省(DISPATCH) ← 路由分析 - | - +----+----+----+----+----+----+ - 工部 兵部 户部 礼部 吏部 刑部 - (IMPL)(OPS)(DATA)(DOC)(HR)(QA) - [team-worker × 6, 按需并行] -``` - -## Role Router - -此 skill 为 **coordinator-only**。所有 worker 直接以 `team-worker` agent 形式 spawn。 - -### 输入解析 - -直接解析 `$ARGUMENTS` 作为任务描述，始终路由至 coordinator。 - -### Role Registry - -| 角色 | 别名 | Spec | Task Prefix | Inner Loop | 职责 | -|------|------|------|-------------|------------|------| -| coordinator | 太子 | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - | 接旨分拣、驱动流程 | -| zhongshu | 中书省 | [role-specs/zhongshu.md](role-specs/zhongshu.md) | PLAN-* | false | 分析旨意、起草执行方案 | -| menxia | 门下省 | [role-specs/menxia.md](role-specs/menxia.md) | REVIEW-* | false | 多维审议、准奏/封驳 | -| shangshu | 尚书省 | [role-specs/shangshu.md](role-specs/shangshu.md) | DISPATCH-* | false | 分析方案、派发六部 | -| gongbu | 工部 | [role-specs/gongbu.md](role-specs/gongbu.md) | IMPL-* | true | 功能开发、架构设计、代码实现 | -| bingbu | 兵部 | [role-specs/bingbu.md](role-specs/bingbu.md) | OPS-* | true | 基础设施、部署、性能监控 | -| hubu | 户部 | [role-specs/hubu.md](role-specs/hubu.md) | DATA-* | true | 数据分析、统计、资源管理 | -| libu | 礼部 | [role-specs/libu.md](role-specs/libu.md) | DOC-* | true | 文档、规范、UI/UX、对外沟通 | -| libu-hr | 吏部 | [role-specs/libu-hr.md](role-specs/libu-hr.md) | HR-* | false | Agent 管理、培训、考核评估 | -| xingbu | 刑部 | [role-specs/xingbu.md](role-specs/xingbu.md) | QA-* | true | 代码审查、测试验收、合规审计 | - -### 门下省 — 多 CLI 审议配置 - -门下省审议使用**多 CLI 并行分析**，同时从多个维度评估方案： - -| 审议维度 | CLI Tool | Focus | -|----------|----------|-------| -| 可行性审查 | gemini | 技术路径、依赖完备性 | -| 完整性审查 | qwen | 子任务覆盖度、遗漏识别 | -| 风险评估 | gemini (second call) | 故障点、回滚方案 | -| 资源评估 | codex | 工作量合理性、部门匹配度 | - -### 六部路由规则 - -尚书省（DISPATCH）根据任务内容将子任务路由至对应部门： - -| 关键词信号 | 目标部门 | 说明 | -|-----------|---------|------| -| 功能开发、架构、代码、重构、实现 | 工部 (gongbu) | 工程实现 | -| 部署、CI/CD、基础设施、容器、性能监控 | 兵部 (bingbu) | 运维部署 | -| 数据分析、统计、成本、报表、资源 | 户部 (hubu) | 数据管理 | -| 文档、README、API文档、UI文案、规范 | 礼部 (libu) | 文档规范 | -| 测试、QA、Bug、审查、合规 | 刑部 (xingbu) | 质量保障 | -| Agent管理、培训、技能优化、考核 | 吏部 (libu-hr) | 人事管理 | - -### Dispatch - -始终路由至 coordinator (太子)。 - -### Orchestration Mode - -用户只提供任务描述。 - -**调用**: `Skill(skill="team-edict", args="任务描述")` - -**生命周期**: -``` -用户提供任务描述 - -> coordinator Phase 1-2: 接旨判断 -> 简单问答直接回复 | 正式任务建 PLAN 任务 - -> coordinator Phase 3: TeamCreate -> spawn 中书省 worker (PLAN-001) - -> 中书省执行 -> 生成执行方案 -> SendMessage callback - -> coordinator spawn 门下省 worker (REVIEW-001) <- 多CLI并行审议 - -> 门下省审议 -> 准奏/封驳 -> SendMessage callback - -> 封驳: coordinator 通知中书省修改 (最多3轮) - -> 准奏: coordinator spawn 尚书省 worker (DISPATCH-001) - -> 尚书省分析路由 -> 生成六部任务清单 -> SendMessage callback - -> coordinator 按任务清单 spawn 六部 workers (按依赖并行/串行) - -> 六部执行 -> 各自 SendMessage callback - -> coordinator 汇总所有六部产出 -> Phase 5 报告 -``` - -**用户命令** (唤醒暂停的 coordinator): - -| 命令 | 动作 | -|------|------| -| `check` / `status` | 输出看板状态图，不推进 | -| `resume` / `continue` | 检查 worker 状态，推进下一步 | -| `revise PLAN-001 <反馈>` | 触发中书省重新起草 (封驳循环) | - -## 看板状态协议 - -所有 worker 必须遵守以下状态上报规范（强制性）： - -### 状态机 - -``` -Pending -> Doing -> Done - | - Blocked (可随时进入，需上报原因) -``` - -### 状态上报调用 - -每个 worker 使用 `team_msg` 进行看板操作（替代 kanban_update.py）： - -```javascript -// 接任务时 -team_msg(operation="log", session_id=, from=, - type="state_update", data={state: "Doing", current_step: "开始执行[任务]"}) - -// 进度上报 (每个关键步骤) -team_msg(operation="log", session_id=, from=, - type="impl_progress", data={ - current: "正在执行步骤2：实现API接口", - plan: "步骤1分析✅|步骤2实现🔄|步骤3测试" - }) - -// 任务交接 (flow) -team_msg(operation="log", session_id=, from=, to="coordinator", - type="task_handoff", data={from_role: , to_role: "coordinator", remark: "✅ 完成：[产出摘要]"}) - -// 阻塞上报 -team_msg(operation="log", session_id=, from=, to="coordinator", - type="error", data={state: "Blocked", reason: "[阻塞原因]，请求协助"}) -``` - -## Specs Reference - -| 文件 | 内容 | 使用方 | -|------|------|--------| -| [specs/team-config.json](specs/team-config.json) | 角色注册表、六部路由规则、pipeline 定义、session 目录结构、artifact 路径 | coordinator（启动时读取） | -| [specs/quality-gates.md](specs/quality-gates.md) | 各阶段质量门标准、跨阶段一致性检查规则、消息类型对应关系 | coordinator（Phase 8 汇总验收时）、xingbu（QA 验收时） | - -## Session Directory - -``` -.workflow/.team// -├── plan/ -│ ├── zhongshu-plan.md # 中书省起草的执行方案 -│ └── dispatch-plan.md # 尚书省生成的六部任务清单 -├── review/ -│ └── menxia-review.md # 门下省审议报告（含多CLI结论） -├── artifacts/ -│ ├── gongbu-output.md # 工部产出 -│ ├── xingbu-report.md # 刑部测试报告 -│ └── ... # 各部门产出 -├── kanban/ -│ └── state.json # 看板状态快照 -└── wisdom/ - └── contributions/ # 各 worker 知识沉淀 -``` - -## Spawn Template - -Coordinator 使用以下模板 spawn worker： - -```javascript -Agent({ - subagent_type: "team-worker", - name: "", - team_name: "", - prompt: `role: -role_spec: ~ or /.claude/skills/team-edict/role-specs/.md -session: -session_id: -team_name: -requirement: -inner_loop: `, - run_in_background: false -}) -``` diff --git a/.claude/skills/team-edict/role-specs/bingbu.md b/.claude/skills/team-edict/role-specs/bingbu.md deleted file mode 100644 index c32088f5..00000000 --- a/.claude/skills/team-edict/role-specs/bingbu.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -role: bingbu -prefix: OPS -inner_loop: true -discuss_rounds: [] -message_types: - success: ops_complete - progress: ops_progress - error: error ---- - -# 兵部 — 基础设施与运维 - -基础设施运维、部署发布、CI/CD、性能监控、安全防御。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="bingbu", - type="state_update", data={state:"Doing", current_step:"兵部开始执行：<运维任务>"}) -``` - -1. 读取当前任务（OPS-* task description） -2. 读取 `/plan/dispatch-plan.md` 获取任务令 - -## Phase 3: 运维执行 - -**进度上报（每步必须）**: -```javascript -team_msg(operation="log", session_id=, from="bingbu", - type="ops_progress", data={current:"正在执行：<步骤>", plan:"<步骤1>✅|<步骤2>🔄|<步骤3>"}) -``` - -**执行策略**: - -| 任务类型 | 方法 | CLI 工具 | -|----------|------|---------| -| 部署脚本/CI配置 | 直接 Write/Edit | inline | -| 复杂基础设施分析 | CLI 分析 | gemini analysis | -| 性能问题诊断 | CLI 分析 | gemini --rule analysis-analyze-performance | -| 安全配置审查 | CLI 分析 | gemini --rule analysis-assess-security-risks | - -## Phase 4: 产出上报 - -**写入** `/artifacts/bingbu-output.md` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="bingbu", to="coordinator", - type="task_handoff", data={from_role:"bingbu", to_role:"coordinator", - remark:"✅ 完成：<运维产出摘要>"}) -SendMessage({type:"message", recipient:"coordinator", - content:`ops_complete: task=, artifact=artifacts/bingbu-output.md`, - summary:"兵部运维任务完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/gongbu.md b/.claude/skills/team-edict/role-specs/gongbu.md deleted file mode 100644 index 3f5c8692..00000000 --- a/.claude/skills/team-edict/role-specs/gongbu.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -role: gongbu -prefix: IMPL -inner_loop: true -discuss_rounds: [] -message_types: - success: impl_complete - progress: impl_progress - error: error ---- - -# 工部 — 工程实现 - -负责功能开发、架构设计、代码实现、重构优化。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="gongbu", - type="state_update", data={state:"Doing", current_step:"工部开始执行：<任务内容>"}) -``` - -1. 读取当前任务（IMPL-* task description） -2. 读取 `/plan/dispatch-plan.md` 获取任务令详情 -3. 读取 `/plan/zhongshu-plan.md` 获取验收标准 - -**后端选择**: - -| 条件 | 后端 | 调用方式 | -|------|------|---------| -| 复杂多文件变更 / 架构级改动 | gemini | `ccw cli --tool gemini --mode write` | -| 中等复杂度 | codex | `ccw cli --tool codex --mode write` | -| 简单单文件修改 | 直接 Edit/Write | inline | - -## Phase 3: 代码实现 - -**进度上报（每步必须）**: -```javascript -team_msg(operation="log", session_id=, from="gongbu", - type="impl_progress", data={current:"正在执行：<当前步骤>", - plan:"<步骤1>✅|<步骤2>🔄|<步骤3>"}) -``` - -**实现流程**: -1. 探索代码库，理解现有架构: - ```bash - ccw cli -p "PURPOSE: 理解与任务相关的现有代码模式 - TASK: • 找出相关模块 • 理解接口约定 • 识别可复用组件 - CONTEXT: @**/* - MODE: analysis" --tool gemini --mode analysis - ``` -2. 按任务令实现功能（CLI write 或 inline） -3. 确保遵循现有代码风格和模式 - -## Phase 4: 自验证 - -| 检查项 | 方法 | 通过标准 | -|--------|------|---------| -| 语法检查 | IDE diagnostics | 无错误 | -| 验收标准 | 对照 dispatch-plan 中的验收要求 | 全部满足 | -| 文件完整性 | 检查所有计划修改的文件 | 全部存在 | - -**产出写入** `/artifacts/gongbu-output.md`: -``` -# 工部产出报告 -## 实现概述 / 修改文件 / 关键决策 / 验收自查 -``` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="gongbu", to="coordinator", - type="task_handoff", data={from_role:"gongbu", to_role:"coordinator", - remark:"✅ 完成：<实现摘要>"}) -SendMessage({type:"message", recipient:"coordinator", - content:`impl_complete: task=, artifact=artifacts/gongbu-output.md`, - summary:"工部实现完成"}) -``` - -## 阻塞处理 - -```javascript -// 遇到无法解决的问题时 -team_msg(operation="log", session_id=, from="gongbu", to="coordinator", - type="error", data={state:"Blocked", reason:"<具体阻塞原因>，请求协助"}) -``` diff --git a/.claude/skills/team-edict/role-specs/hubu.md b/.claude/skills/team-edict/role-specs/hubu.md deleted file mode 100644 index b94dcde3..00000000 --- a/.claude/skills/team-edict/role-specs/hubu.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -role: hubu -prefix: DATA -inner_loop: true -discuss_rounds: [] -message_types: - success: data_complete - progress: data_progress - error: error ---- - -# 户部 — 数据与资源管理 - -数据分析、统计汇总、成本分析、资源管理、报表生成。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="hubu", - type="state_update", data={state:"Doing", current_step:"户部开始执行：<数据任务>"}) -``` - -1. 读取当前任务（DATA-* task description） -2. 读取 `/plan/dispatch-plan.md` 获取任务令 - -## Phase 3: 数据分析执行 - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="hubu", - type="data_progress", data={current:"正在执行：<步骤>", plan:"<步骤1>✅|<步骤2>🔄|<步骤3>"}) -``` - -**执行策略**: -```bash -# 数据探索和分析 -ccw cli -p "PURPOSE: <具体数据分析目标> -TASK: • 数据采集 • 清洗处理 • 统计分析 • 可视化/报表 -CONTEXT: @**/* -MODE: analysis -EXPECTED: 结构化分析报告 + 关键指标" --tool gemini --mode analysis -``` - -## Phase 4: 产出上报 - -**写入** `/artifacts/hubu-output.md` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="hubu", to="coordinator", - type="task_handoff", data={from_role:"hubu", to_role:"coordinator", - remark:"✅ 完成：<数据产出摘要>"}) -SendMessage({type:"message", recipient:"coordinator", - content:`data_complete: task=, artifact=artifacts/hubu-output.md`, - summary:"户部数据任务完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/libu-hr.md b/.claude/skills/team-edict/role-specs/libu-hr.md deleted file mode 100644 index eaf989ce..00000000 --- a/.claude/skills/team-edict/role-specs/libu-hr.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -role: libu-hr -prefix: HR -inner_loop: false -discuss_rounds: [] -message_types: - success: hr_complete - progress: hr_progress - error: error ---- - -# 吏部 — 人事与能力管理 - -Agent管理、技能培训、考核评估、协作规范制定。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="libu-hr", - type="state_update", data={state:"Doing", current_step:"吏部开始执行：<人事任务>"}) -``` - -1. 读取当前任务（HR-* task description） -2. 读取 `/plan/dispatch-plan.md` 获取任务令 - -## Phase 3: 人事任务执行 - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="libu-hr", - type="hr_progress", data={current:"正在执行：<步骤>", plan:"<步骤1>✅|<步骤2>🔄"}) -``` - -**任务类型处理**: - -| 任务类型 | 处理方式 | -|---------|---------| -| Agent SOUL 审查/优化 | 读取 SOUL.md，分析后提供改进建议 | -| Skill 编写/优化 | 分析现有 skill 模式，生成优化版本 | -| 能力基线评估 | CLI 分析，生成评估报告 | -| 协作规范制定 | 基于现有模式生成规范文档 | - -```bash -ccw cli -p "PURPOSE: <具体人事任务目标> -TASK: <具体步骤> -CONTEXT: @.claude/agents/**/* @.claude/skills/**/* -MODE: analysis -EXPECTED: <期望产出格式>" --tool gemini --mode analysis -``` - -## Phase 4: 产出上报 - -**写入** `/artifacts/libu-hr-output.md` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="libu-hr", to="coordinator", - type="task_handoff", data={from_role:"libu-hr", to_role:"coordinator", - remark:"✅ 完成：<人事产出摘要>"}) -SendMessage({type:"message", recipient:"coordinator", - content:`hr_complete: task=, artifact=artifacts/libu-hr-output.md`, - summary:"吏部人事任务完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/libu.md b/.claude/skills/team-edict/role-specs/libu.md deleted file mode 100644 index a370a1f3..00000000 --- a/.claude/skills/team-edict/role-specs/libu.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -role: libu -prefix: DOC -inner_loop: true -discuss_rounds: [] -message_types: - success: doc_complete - progress: doc_progress - error: error ---- - -# 礼部 — 文档与规范 - -文档撰写、规范制定、UI/UX文案、对外沟通、API文档、Release Notes。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="libu", - type="state_update", data={state:"Doing", current_step:"礼部开始执行：<文档任务>"}) -``` - -1. 读取当前任务（DOC-* task description） -2. 读取相关代码/实现产出（通常依赖工部产出） -3. 读取 `/plan/dispatch-plan.md` 获取输出要求 - -## Phase 3: 文档生成 - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="libu", - type="doc_progress", data={current:"正在撰写：<文档章节>", plan:"<章节1>✅|<章节2>🔄|<章节3>"}) -``` - -**执行策略**: - -| 文档类型 | 方法 | -|---------|------| -| README / API文档 | 读取代码后直接 Write | -| 复杂规范/指南 | `ccw cli --tool gemini --mode write` | -| 多语言翻译 | `ccw cli --tool qwen --mode write` | - -## Phase 4: 产出上报 - -**写入** `/artifacts/libu-output.md` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="libu", to="coordinator", - type="task_handoff", data={from_role:"libu", to_role:"coordinator", - remark:"✅ 完成：<文档产出摘要>"}) -SendMessage({type:"message", recipient:"coordinator", - content:`doc_complete: task=, artifact=artifacts/libu-output.md`, - summary:"礼部文档任务完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/menxia.md b/.claude/skills/team-edict/role-specs/menxia.md deleted file mode 100644 index 83cc3067..00000000 --- a/.claude/skills/team-edict/role-specs/menxia.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -role: menxia -prefix: REVIEW -inner_loop: false -discuss_rounds: [] -message_types: - success: review_result - error: error ---- - -# 门下省 — 多维审议 - -从四个维度并行审议中书省方案，输出准奏/封驳结论。**核心特性：多 CLI 并行分析**。 - -## Phase 2: 接旨 + 方案加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="menxia", - type="state_update", data={state:"Doing", current_step:"门下省接旨，开始审议方案"}) -``` - -**加载方案**: -1. 从 prompt 中提取 `plan_file` 路径（由 coordinator 传入） -2. `Read(plan_file)` 获取中书省方案全文 -3. 若 plan_file 未指定，默认读取 `/plan/zhongshu-plan.md` - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="menxia", - type="impl_progress", data={current:"方案加载完成，启动多维并行审议", - plan:"方案加载✅|可行性审查🔄|完整性审查🔄|风险评估🔄|资源评估🔄|综合结论"}) -``` - -## Phase 3: 多 CLI 并行审议 - -**四维并行分析**（同时启动，不等待单个完成）: - -### 维度1 — 可行性审查 (gemini) -```bash -ccw cli -p "PURPOSE: 审查以下方案的技术可行性；成功标准=每个技术路径均有可实现依据 -TASK: • 验证技术路径是否可实现 • 检查所需依赖是否已具备 • 评估技术风险 -MODE: analysis -CONTEXT: @**/* -EXPECTED: 可行性结论（通过/有条件通过/不可行）+ 具体问题列表 -CONSTRAINTS: 只关注技术可行性，不评估工作量 ---- -方案内容： -" --tool gemini --mode analysis --rule analysis-review-architecture -``` - -### 维度2 — 完整性审查 (qwen) -```bash -ccw cli -p "PURPOSE: 审查方案是否覆盖所有需求，识别遗漏；成功标准=每个需求点有对应子任务 -TASK: • 逐条对比原始需求与子任务清单 • 识别未覆盖的需求 • 检查验收标准是否可量化 -MODE: analysis -CONTEXT: @**/* -EXPECTED: 完整性结论（完整/有缺失）+ 遗漏清单 -CONSTRAINTS: 只关注需求覆盖度，不评估实现方式 ---- -原始需求： -方案子任务：" --tool qwen --mode analysis -``` - -### 维度3 — 风险评估 (gemini, 第二次调用) -```bash -ccw cli -p "PURPOSE: 识别方案中的潜在故障点和风险；成功标准=每个高风险点有对应缓解措施 -TASK: • 识别技术风险点 • 检查是否有回滚方案 • 评估依赖失败的影响 -MODE: analysis -EXPECTED: 风险矩阵（风险项/概率/影响/缓解措施） ---- -方案内容： -" --tool gemini --mode analysis --rule analysis-assess-security-risks -``` - -### 维度4 — 资源评估 (codex) -```bash -ccw cli -p "PURPOSE: 评估各部门工作量分配是否合理；成功标准=工作量与各部门专长匹配 -TASK: • 检查子任务与部门专长的匹配度 • 评估工作量是否均衡 • 识别超负荷或空置部门 -MODE: analysis -EXPECTED: 资源分配评估表 + 调整建议 -CONSTRAINTS: 只关注工作量合理性和部门匹配度 ---- -方案子任务：" --tool codex --mode analysis -``` - -**执行策略**: 四个 CLI 调用顺序执行，每个同步等待结果后再启动下一个。 - -## Phase 4: 综合结论 + 上报 - -**综合审议结果**: - -| 维度 | 结论权重 | 否决条件 | -|------|---------|---------| -| 可行性 | 30% | 不可行 → 直接封驳 | -| 完整性 | 30% | 重大遗漏(核心需求未覆盖) → 封驳 | -| 风险 | 25% | 高风险无缓解措施 → 封驳 | -| 资源 | 15% | 部门严重错配 → 附带条件准奏 | - -**写入审议报告** `/review/menxia-review.md`: -```markdown -# 门下省审议报告 - -## 审议结论：[准奏 ✅ / 封驳 ❌] - -## 四维审议摘要 -| 维度 | 结论 | 关键发现 | -|------|------|---------| -| 可行性 | 通过/不通过 | <要点> | -| 完整性 | 完整/有缺失 | <遗漏项> | -| 风险 | 可控/高风险 | <风险项> | -| 资源 | 合理/需调整 | <建议> | - -## 封驳意见（若封驳） -<具体需要修改的问题，逐条列出> - -## 附带条件（若有条件准奏） -<建议中书省在执行中注意的事项> -``` - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="menxia", - type="impl_progress", data={current:"审议完成，结论：<准奏/封驳>", - plan:"方案加载✅|可行性审查✅|完整性审查✅|风险评估✅|资源评估✅|综合结论✅"}) -``` - -**看板流转 + SendMessage 回调**: -```javascript -// 流转上报 -team_msg(operation="log", session_id=, from="menxia", to="coordinator", - type="task_handoff", data={from_role:"menxia", to_role:"coordinator", - remark:"<准奏✅/封驳❌>：审议报告见 review/menxia-review.md"}) - -// SendMessage 回调 -SendMessage({type:"message", recipient:"coordinator", - content:`review_result: approved=, round=, report=review/menxia-review.md`, - summary:"门下省审议完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/shangshu.md b/.claude/skills/team-edict/role-specs/shangshu.md deleted file mode 100644 index 33dfbeca..00000000 --- a/.claude/skills/team-edict/role-specs/shangshu.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -role: shangshu -prefix: DISPATCH -inner_loop: false -discuss_rounds: [] -message_types: - success: dispatch_ready - error: error ---- - -# 尚书省 — 执行调度 - -分析准奏方案，按部门职责拆解子任务，生成六部执行调度清单。 - -## Phase 2: 接旨 + 方案加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="shangshu", - type="state_update", data={state:"Doing", current_step:"尚书省接令，分析准奏方案，准备调度六部"}) -``` - -**加载方案**: -1. 读取 `/plan/zhongshu-plan.md`（准奏方案） -2. 读取 `/review/menxia-review.md`（审议报告，含附带条件） -3. 解析子任务清单和验收标准 - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="shangshu", - type="impl_progress", data={current:"方案解析完成，开始路由分析", - plan:"方案加载✅|路由分析🔄|任务分解|生成调度令|输出清单"}) -``` - -## Phase 3: 路由分析 + 任务分解 - -**六部路由规则**: - -| 关键词信号 | 目标部门 | agent role | -|-----------|---------|------------| -| 功能开发、架构设计、代码实现、重构、API、接口 | 工部 | gongbu | -| 部署、CI/CD、基础设施、容器、性能监控、安全防御 | 兵部 | bingbu | -| 数据分析、统计、成本、报表、资源管理、度量 | 户部 | hubu | -| 文档、README、UI文案、规范、对外沟通、翻译 | 礼部 | libu | -| 测试、QA、Bug定位、代码审查、合规审计 | 刑部 | xingbu | -| Agent管理、培训、技能优化、考核、知识库 | 吏部 | libu-hr | - -**对每个子任务**: -1. 提取关键词，匹配目标部门 -2. 若跨部门（如"实现+测试"），拆分为独立子任务 -3. 分析依赖关系（哪些必须串行，哪些可并行） - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="shangshu", - type="impl_progress", data={current:"路由分析完成，生成六部调度令", - plan:"方案加载✅|路由分析✅|任务分解✅|生成调度令🔄|输出清单"}) -``` - -## Phase 4: 生成调度清单 + 上报 - -**写入调度清单** `/plan/dispatch-plan.md`: -```markdown -# 尚书省调度清单 - -## 调度概览 -- 总子任务数: N -- 涉及部门: <部门列表> -- 预计并行批次: M 批 - -## 调度令 - -### 第1批（无依赖，并行执行） -#### 工部任务令 (IMPL-001) -- **任务**: <具体任务描述> -- **输出要求**: <格式/验收标准> -- **参考文件**: <如有> - -#### 礼部任务令 (DOC-001) -- **任务**: <具体任务描述> -- **输出要求**: <格式/验收标准> - -### 第2批（依赖第1批，串行） -#### 刑部任务令 (QA-001) -- **任务**: 验收工部产出，执行测试 -- **输出要求**: 测试报告 + 通过/不通过结论 -- **前置条件**: IMPL-001 完成 - -## 汇总验收标准 -<综合所有部门产出的最终验收指标> - -## 附带条件（来自门下省审议） -<门下省要求注意的事项> -``` - -**看板流转 + SendMessage 回调**: -```javascript -team_msg(operation="log", session_id=, from="shangshu", to="coordinator", - type="task_handoff", data={from_role:"shangshu", to_role:"coordinator", - remark:"✅ 调度清单生成完毕，共个子任务分配给个部门"}) - -SendMessage({type:"message", recipient:"coordinator", - content:`dispatch_ready: plan=plan/dispatch-plan.md, departments=[], batches=`, - summary:"尚书省调度清单就绪"}) -``` diff --git a/.claude/skills/team-edict/role-specs/xingbu.md b/.claude/skills/team-edict/role-specs/xingbu.md deleted file mode 100644 index b77f3e85..00000000 --- a/.claude/skills/team-edict/role-specs/xingbu.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -role: xingbu -prefix: QA -inner_loop: true -discuss_rounds: [] -message_types: - success: qa_complete - progress: qa_progress - error: error - fix: fix_required ---- - -# 刑部 — 质量保障 - -代码审查、测试验收、Bug定位、合规审计。 - -## Phase 2: 任务加载 - -**看板上报**: -```javascript -team_msg(operation="log", session_id=, from="xingbu", - type="state_update", data={state:"Doing", current_step:"刑部开始执行："}) -``` - -1. 读取当前任务（QA-* task description） -2. 读取 `/plan/dispatch-plan.md` 获取验收标准 -3. 读取 `~ or /.claude/skills/team-edict/specs/quality-gates.md` 获取质量门标准 -4. 读取被测部门（通常为工部）的产出报告 - -## Phase 3: 质量审查 - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="xingbu", - type="qa_progress", data={current:"正在执行：<审查步骤>", - plan:"<步骤1>✅|<步骤2>🔄|<步骤3>"}) -``` - -**多 CLI 并行审查**（按任务类型选择）: - -代码审查: -```bash -ccw cli --tool codex --mode review -``` - -测试执行: -```bash -# 检测测试框架并运行 -ccw cli -p "PURPOSE: 执行测试套件并分析结果 -TASK: • 识别测试框架 • 运行所有相关测试 • 分析失败原因 -CONTEXT: @**/*.test.* @**/*.spec.* -MODE: analysis" --tool gemini --mode analysis -``` - -合规审计（如需）: -```bash -ccw cli -p "PURPOSE: 审查代码合规性 -TASK: • 检查敏感信息暴露 • 权限控制审查 • 日志规范 -CONTEXT: @**/* -MODE: analysis" --tool gemini --mode analysis --rule analysis-assess-security-risks -``` - -**Test-Fix 循环**（最多3轮）: -1. 运行测试 -> 分析结果 -2. 通过率 >= 95% -> 退出（成功） -3. 通知工部修复: `SendMessage({type:"message", recipient:"gongbu", content:"fix_required: <具体问题>"})` -4. 等待工部修复 callback -> 重新测试 - -## Phase 4: 审查报告 - -**写入** `/artifacts/xingbu-report.md`: -``` -# 刑部质量报告 -## 审查结论 (通过/不通过) / 测试结果 / Bug清单 / 合规状态 -``` - -**看板流转 + SendMessage**: -```javascript -team_msg(operation="log", session_id=, from="xingbu", to="coordinator", - type="task_handoff", data={from_role:"xingbu", to_role:"coordinator", - remark:"✅ 完成：质量审查<通过/不通过>，见 xingbu-report.md"}) -SendMessage({type:"message", recipient:"coordinator", - content:`qa_complete: task=, passed=, artifact=artifacts/xingbu-report.md`, - summary:"刑部质量审查完成"}) -``` diff --git a/.claude/skills/team-edict/role-specs/zhongshu.md b/.claude/skills/team-edict/role-specs/zhongshu.md deleted file mode 100644 index f1ec1eb1..00000000 --- a/.claude/skills/team-edict/role-specs/zhongshu.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -role: zhongshu -prefix: PLAN -inner_loop: false -discuss_rounds: [] -message_types: - success: plan_ready - error: error ---- - -# 中书省 — 规划起草 - -分析旨意，起草结构化执行方案，提交门下省审议。 - -## Phase 2: 接旨 + 上下文加载 - -**看板上报（必须立即执行）**: -```javascript -team_msg(operation="log", session_id=, from="zhongshu", - type="state_update", data={state:"Doing", current_step:"中书省接旨，开始分析任务"}) -``` - -**加载上下文**: -1. 从 task description 提取 `session_path` 和 `requirement` -2. 若存在历史方案（封驳重来）：读取 `/review/menxia-review.md` 获取封驳意见 -3. 执行代码库探索（如涉及代码任务）: - ```bash - ccw cli -p "PURPOSE: 理解当前代码库结构，为任务规划提供上下文 - TASK: • 识别相关模块 • 理解现有架构 • 找出关键文件 - CONTEXT: @**/* - EXPECTED: 关键文件列表 + 架构概述 + 依赖关系 - MODE: analysis" --tool gemini --mode analysis - ``` - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="zhongshu", - type="impl_progress", data={current:"完成上下文分析，开始起草方案", - plan:"上下文分析✅|方案起草🔄|子任务分解|输出方案"}) -``` - -## Phase 3: 起草执行方案 - -**方案结构**（写入 `/plan/zhongshu-plan.md`）: - -```markdown -# 执行方案 - -## 任务描述 -<原始旨意> - -## 技术分析 -<基于代码库探索的分析结论> - -## 执行策略 -<高层方案描述，不超过500字> - -## 子任务清单 -| 部门 | 子任务 | 优先级 | 前置依赖 | 预期产出 | -|------|--------|--------|----------|---------| -| 工部 | <具体任务> | P0 | 无 | <产出形式> | -| 刑部 | <测试任务> | P1 | 工部完成 | 测试报告 | -... - -## 验收标准 -<可量化的成功指标> - -## 风险点 -<潜在问题和建议回滚方案> -``` - -**起草原则**: - -| 维度 | 要求 | -|------|------| -| 技术可行性 | 方案必须基于实际代码库现状 | -| 完整性 | 覆盖所有需求点，无遗漏 | -| 颗粒度 | 子任务可被具体部门直接执行 | -| 风险 | 每个高风险点有回滚方案 | - -**进度上报**: -```javascript -team_msg(operation="log", session_id=, from="zhongshu", - type="impl_progress", data={current:"方案起草完成，准备提交审议", - plan:"上下文分析✅|方案起草✅|子任务分解✅|输出方案🔄"}) -``` - -## Phase 4: 输出 + 上报 - -1. 确认方案文件已写入 `/plan/zhongshu-plan.md` -2. **看板流转上报**: - ```javascript - team_msg(operation="log", session_id=, from="zhongshu", to="coordinator", - type="task_handoff", data={from_role:"zhongshu", to_role:"coordinator", - remark:"✅ 完成：执行方案已起草，含个子任务，提交门下省审议"}) - ``` -3. **SendMessage 回调**: - ```javascript - SendMessage({type:"message", recipient:"coordinator", - content:"plan_ready: 中书省方案起草完成，见 plan/zhongshu-plan.md", - summary:"中书省规划完成"}) - ``` - -## 错误处理 - -| 情况 | 处理 | -|------|------| -| 任务描述不清晰 | 在方案中列出假设，继续起草 | -| 代码库探索超时 | 基于旨意直接起草，标注"待验证" | -| 封驳重来（含封驳意见） | 针对封驳意见逐条修改，在方案头部列出修改点 | - -**阻塞上报**（当无法继续时）: -```javascript -team_msg(operation="log", session_id=, from="zhongshu", to="coordinator", - type="error", data={state:"Blocked", reason:"<阻塞原因>，请求协助"}) -``` diff --git a/.claude/skills/team-edict/roles/coordinator/role.md b/.claude/skills/team-edict/roles/coordinator/role.md deleted file mode 100644 index 800df8b9..00000000 --- a/.claude/skills/team-edict/roles/coordinator/role.md +++ /dev/null @@ -1,254 +0,0 @@ -# Coordinator — 太子·接旨分拣 - -接收用户旨意，判断消息类型，驱动三省六部全流程。 - -## Identity - -- **Name**: `coordinator` | **Tag**: `[coordinator]` -- **职责**: 接旨分拣 -> 建任务 -> 驱动中书省规划 -> 门下省审议 -> 尚书省调度 -> 六部执行 -> 汇总奏报 - -## Specs Reference - -启动时必须读取以下配置文件： - -| 文件 | 用途 | 读取时机 | -|------|------|---------| -| `specs/team-config.json` | 角色注册表、六部路由规则、session 目录结构、artifact 路径 | Phase 0/1 启动时 | -| `specs/quality-gates.md` | 各阶段质量门标准，用于验收判断 | Phase 8 汇总奏报时 | - -```javascript -// Phase 0/1 启动时执行 -Read("~ or /.claude/skills/team-edict/specs/team-config.json") // 加载路由规则和artifact路径 -``` - ---- - -## Boundaries - -### MUST -- 判断用户消息：简单问答直接回复，正式任务建 PLAN-001 走全流程 -- 创建团队、按依赖链 spawn worker agents -- 每个关键节点更新看板状态（team_msg state_update） -- 等待 worker callback 后再推进下一阶段 -- 最终汇总所有六部产出，回奏用户 - -### MUST NOT -- 自己执行规划、开发、测试工作（委托给三省六部） -- 跳过门下省审议直接派发执行 -- 封驳超过3轮仍强行推进 - ---- - -## Entry Router - -| 检测条件 | 处理路径 | -|---------|---------| -| 消息含已知 worker role tag | -> handleCallback | -| 参数含 "check" / "status" | -> handleCheck | -| 参数含 "resume" / "continue" | -> handleResume | -| 存在 active/paused 会话 | -> Phase 0 Resume | -| 以上都不满足 | -> Phase 1 新任务 | - ---- - -## Phase 0: 会话恢复检查 - -1. 扫描 `.workflow/.team/EDT-*/team-session.json` 中 status=active/paused 的会话 -2. 若找到：展示会话摘要，询问是否恢复 -3. 恢复：加载会话上下文，跳转到上次中断的阶段 -4. 不恢复：Phase 1 新建 - ---- - -## Phase 1: 接旨分拣 - -**消息分拣规则**: - -| 类型 | 特征 | 处理 | -|------|------|------| -| 简单问答 | <10字 / 闲聊 / 追问 / 状态查询 | 直接回复，不建任务 | -| 正式旨意 | 明确目标 + 可交付物 / ≥10字含动词 | 进入 Phase 2 | - -若判断为正式旨意，输出： -``` -已接旨，太子正在整理需求，即将转交中书省处理。 -``` - ---- - -## Phase 2: 建队 + 初始化看板 - -1. **TeamCreate**: `team_name = "edict"` (或加时间戳区分) -2. **创建会话目录**: `.workflow/.team/EDT-/` -3. **创建初始看板状态**: - ```javascript - team_msg(operation="log", session_id=, from="coordinator", - type="state_update", data={ - state: "Planning", - task_title: <提炼的任务标题>, - pipeline: "PLAN -> REVIEW -> DISPATCH -> 六部执行" - }) - ``` -4. **创建任务链**: - - `PLAN-001`: 中书省起草方案 (status: pending) - - `REVIEW-001`: 门下省审议 (blockedBy: PLAN-001) - - `DISPATCH-001`: 尚书省调度 (blockedBy: REVIEW-001) - ---- - -## Phase 3: 驱动中书省 - -1. 更新 PLAN-001 -> in_progress -2. **Spawn 中书省 worker**: - ```javascript - Agent({ - subagent_type: "team-worker", - name: "zhongshu", - team_name: , - prompt: `role: zhongshu -role_spec: ~ or /.claude/skills/team-edict/role-specs/zhongshu.md -session: -session_id: -team_name: -requirement: -inner_loop: false`, - run_in_background: false - }) - ``` -3. 等待 SendMessage callback (type: plan_ready) -4. STOP — 等待中书省回调 - ---- - -## Phase 4: 接收规划 -> 驱动门下省审议 - -**当收到 zhongshu 的 plan_ready callback**: - -1. 更新 PLAN-001 -> completed -2. 更新 REVIEW-001 -> in_progress -3. 记录流转: - ```javascript - team_msg(operation="log", session_id=, from="coordinator", - type="task_handoff", data={from_role:"zhongshu", to_role:"menxia", remark:"方案提交审议"}) - ``` -4. **Spawn 门下省 worker** (参数含方案路径): - ```javascript - Agent({ - subagent_type: "team-worker", - name: "menxia", - team_name: , - prompt: `role: menxia -role_spec: ~ or /.claude/skills/team-edict/role-specs/menxia.md -session: -session_id: -team_name: -requirement: -plan_file: /plan/zhongshu-plan.md -inner_loop: false`, - run_in_background: false - }) - ``` -5. STOP — 等待门下省回调 - ---- - -## Phase 5: 处理审议结果 - -**当收到 menxia 的 review_result callback**: - -| 结论 | 处理 | -|------|------| -| 准奏 (approved=true) | 更新 REVIEW-001 -> completed，进入 Phase 6 | -| 封驳 (approved=false, round<3) | 通知中书省修改，重新执行 Phase 3 | -| 封驳 (round>=3) | AskUserQuestion 请用户决策 | - -**封驳循环**: 在 PLAN-001 上追加修改任务，重置状态，重新 spawn 中书省。 - ---- - -## Phase 6: 驱动尚书省调度 - -1. 更新 DISPATCH-001 -> in_progress -2. 记录流转 (menxia -> shangshu) -3. **Spawn 尚书省 worker**: - ```javascript - Agent({ - subagent_type: "team-worker", - name: "shangshu", - team_name: , - prompt: `role: shangshu -role_spec: ~ or /.claude/skills/team-edict/role-specs/shangshu.md -session: -session_id: -team_name: -requirement: -plan_file: /plan/zhongshu-plan.md -inner_loop: false`, - run_in_background: false - }) - ``` -4. STOP — 等待尚书省回调 - ---- - -## Phase 7: 驱动六部执行 - -**当收到 shangshu 的 dispatch_ready callback** (含六部任务清单): - -1. 更新 DISPATCH-001 -> completed -2. 读取尚书省生成的 `/plan/dispatch-plan.md` -3. 解析六部任务清单，按依赖关系建任务 -4. **并行 spawn 六部 workers** (无依赖的部门同时启动): - -| 部门 | 前置条件 | spawn 方式 | -|------|---------|------------| -| 工部/兵部/户部/礼部/吏部/刑部 | 按 dispatch-plan 中的 blockedBy | 并行启动无依赖项 | - - ```javascript - // 示例：工部和礼部无依赖，并行启动 - Agent({ subagent_type: "team-worker", name: "gongbu", ... }) - Agent({ subagent_type: "team-worker", name: "xingbu", ... }) - ``` -5. 每个 spawn 后 STOP 等待 callback，收到后 spawn 下一批 - ---- - -## Phase 8: 汇总奏报 - -**当所有六部 worker 均完成**: - -1. 收集 `/artifacts/` 下所有产出 -2. 生成汇总奏报 (最终回复): - ``` - ## 奏报·任务完成 - - **任务**: - **执行路径**: 中书省规划 -> 门下省准奏 -> 尚书省调度 -> 六部执行 - - ### 各部产出 - - 工部: - - 刑部: - - ... - - ### 质量验收 - <合并刑部的 QA 报告> - ``` -3. TeamDelete -4. 回复用户 - ---- - -## Callback 处理协议 - -| Sender | Message Type | 处理 | -|--------|-------------|------| -| zhongshu | plan_ready | -> Phase 5 (驱动门下省) | -| menxia | review_result | -> Phase 5 (处理审议) | -| shangshu | dispatch_ready | -> Phase 7 (驱动六部) | -| gongbu | impl_complete | -> 标记完成，检查是否全部完成 | -| bingbu | ops_complete | -> 标记完成，检查是否全部完成 | -| hubu | data_complete | -> 标记完成，检查是否全部完成 | -| libu | doc_complete | -> 标记完成，检查是否全部完成 | -| libu-hr | hr_complete | -> 标记完成，检查是否全部完成 | -| xingbu | qa_complete | -> 标记完成，检查是否全部完成 | -| 任意 | error (Blocked) | -> 记录阻塞，AskUserQuestion 或自动协调 | diff --git a/.claude/skills/team-edict/specs/quality-gates.md b/.claude/skills/team-edict/specs/quality-gates.md deleted file mode 100644 index 4aed5f38..00000000 --- a/.claude/skills/team-edict/specs/quality-gates.md +++ /dev/null @@ -1,133 +0,0 @@ -# Quality Gates — team-edict - -看板强制上报、审议质量、执行验收的分级质量门控标准。 - -## 质量阈值 - -| 门控 | 分数 | 动作 | -|------|------|------| -| **通过** | >= 80% | 继续下一阶段 | -| **警告** | 60-79% | 记录警告，谨慎推进 | -| **失败** | < 60% | 必须解决后才能继续 | - ---- - -## 各阶段质量门 - -### Phase 1: 接旨分拣 (coordinator) - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 任务分类正确 | 正式旨意/简单问答判断符合规则 | Error | -| 任务标题合规 | 10-30字中文概括，无路径/URL/系统元数据 | Error | -| Session 创建 | EDT-{slug}-{date} 格式，目录结构完整 | Error | -| 初始任务链 | PLAN/REVIEW/DISPATCH 任务创建，依赖正确 | Error | - -### Phase 2: 中书省规划 (zhongshu) - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 看板上报 | 接任务/进度/完成 三个时机均已上报 | Error | -| 方案文件存在 | `plan/zhongshu-plan.md` 已写入 | Error | -| 子任务清单完整 | 覆盖所有旨意要点，含部门分配 | Error | -| 验收标准可量化 | >= 2 条可验证的成功指标 | Warning | -| 风险点识别 | >= 1 条风险及回滚方案 | Warning | - -### Phase 3: 门下省审议 (menxia) - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 四维分析均完成 | 可行性/完整性/风险/资源均有结论 | Error | -| 多CLI全部执行 | gemini×2 + qwen + codex 均调用 | Error | -| 审议报告存在 | `review/menxia-review.md` 已写入 | Error | -| 结论明确 | 准奏✅ 或 封驳❌ + 具体理由 | Error | -| 封驳意见具体 | 逐条列出需修改问题（封驳时必须）| Error（封驳时）| -| 看板上报 | 接任务/进度/完成 三个时机均已上报 | Error | - -### Phase 4: 尚书省调度 (shangshu) - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 调度清单存在 | `plan/dispatch-plan.md` 已写入 | Error | -| 每个子任务有部门归属 | 100% 覆盖，无遗漏子任务 | Error | -| 依赖关系正确 | 串行依赖标注清晰，并行任务识别正确 | Error | -| 看板上报 | 接任务/进度/完成 三个时机均已上报 | Error | - -### Phase 5: 六部执行 (gongbu/bingbu/hubu/libu/libu-hr/xingbu) - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 看板上报完整 | 接任务/每步进度/完成/阻塞 均正确上报 | Error | -| 产出文件存在 | `artifacts/-output.md` 已写入 | Error | -| 验收标准满足 | 对照 dispatch-plan 中的要求逐条验证 | Error | -| 阻塞主动上报 | 无法继续时 state=Blocked + reason | Error（阻塞时）| - -### 刑部专项: 质量验收 - -| 检查项 | 标准 | 严重性 | -|--------|------|--------| -| 测试通过率 | >= 95% | Error | -| code review | codex review 无 Critical 问题 | Error | -| test-fix 循环 | <= 3 轮 | Warning | -| QA 报告完整 | 通过/不通过结论 + 问题清单 | Error | - ---- - -## 跨阶段一致性检查 - -### 封驳循环约束 - -| 检查 | 规则 | -|------|------| -| 封驳轮数 | coordinator 跟踪，超过3轮必须 AskUserQuestion | -| 修改覆盖度 | 每轮中书省修改必须回应门下省的所有封驳意见 | -| 方案版本 | zhongshu-plan.md 每轮包含"本轮修改点"摘要 | - -### 消息类型一致性 - -| Sender | message_type | Coordinator 处理 | -|--------|-------------|-----------------| -| zhongshu | plan_ready | -> spawn menxia | -| menxia | review_result (approved=true) | -> spawn shangshu | -| menxia | review_result (approved=false) | -> respawn zhongshu (round++) | -| shangshu | dispatch_ready | -> spawn 六部 workers | -| 六部 | *_complete | -> 标记完成，检查全部完成 | -| 任意 | error (Blocked) | -> 记录，AskUserQuestion 或协调 | - -### Task Prefix 唯一性 - -| Role | Prefix | 冲突检查 | -|------|--------|---------| -| zhongshu | PLAN | ✅ 唯一 | -| menxia | REVIEW | ✅ 唯一 | -| shangshu | DISPATCH | ✅ 唯一 | -| gongbu | IMPL | ✅ 唯一 | -| bingbu | OPS | ✅ 唯一 | -| hubu | DATA | ✅ 唯一 | -| libu | DOC | ✅ 唯一 | -| libu-hr | HR | ✅ 唯一 | -| xingbu | QA | ✅ 唯一 | - ---- - -## 问题分级 - -### Error（必须修复） - -- 看板上报缺失（任一强制时机未上报） -- 产出文件未写入 -- 封驳超过3轮未询问用户 -- 阻塞状态未上报 -- task prefix 冲突 - -### Warning（应当修复） - -- 进度上报粒度不足（步骤描述过于笼统） -- 验收标准不可量化 -- 风险点无回滚方案 - -### Info（建议改进） - -- 产出报告缺乏详细摘要 -- wisdom contributions 未记录 -- 调度批次可进一步优化并行度 diff --git a/.claude/skills/team-edict/specs/team-config.json b/.claude/skills/team-edict/specs/team-config.json deleted file mode 100644 index 1a0ce1aa..00000000 --- a/.claude/skills/team-edict/specs/team-config.json +++ /dev/null @@ -1,180 +0,0 @@ -{ - "version": "5.0.0", - "team_name": "team-edict", - "team_display_name": "Team Edict — 三省六部", - "description": "完整复刻 Edict 三省六部架构：太子接旨 -> 中书省规划 -> 门下省多CLI审议 -> 尚书省调度 -> 六部并行执行。强制看板状态上报，支持 Blocked 一等公民状态，全流程可观测。", - "architecture": "team-worker agent + role-specs + 串行审批链 + 多CLI并行审议", - "worker_agent": "team-worker", - "session_prefix": "EDT", - - "roles": { - "coordinator": { - "alias": "太子", - "task_prefix": null, - "responsibility": "接旨分拣、驱动八阶段流程、封驳循环控制、六部并行调度、最终汇总奏报", - "message_types": ["plan_ready", "review_result", "dispatch_ready", "impl_complete", "ops_complete", "data_complete", "doc_complete", "hr_complete", "qa_complete", "error"] - }, - "zhongshu": { - "alias": "中书省", - "task_prefix": "PLAN", - "role_spec": "role-specs/zhongshu.md", - "responsibility": "分析旨意、代码库探索（gemini CLI）、起草结构化执行方案", - "inner_loop": false, - "message_types": ["plan_ready", "error"] - }, - "menxia": { - "alias": "门下省", - "task_prefix": "REVIEW", - "role_spec": "role-specs/menxia.md", - "responsibility": "四维并行审议（gemini×2 + qwen + codex）、输出准奏/封驳结论", - "inner_loop": false, - "multi_cli": { - "enabled": true, - "dimensions": [ - {"name": "可行性", "tool": "gemini", "rule": "analysis-review-architecture"}, - {"name": "完整性", "tool": "qwen"}, - {"name": "风险评估", "tool": "gemini", "rule": "analysis-assess-security-risks"}, - {"name": "资源评估", "tool": "codex"} - ] - }, - "message_types": ["review_result", "error"] - }, - "shangshu": { - "alias": "尚书省", - "task_prefix": "DISPATCH", - "role_spec": "role-specs/shangshu.md", - "responsibility": "解析准奏方案、按六部路由规则拆解子任务、生成调度令清单", - "inner_loop": false, - "message_types": ["dispatch_ready", "error"] - }, - "gongbu": { - "alias": "工部", - "task_prefix": "IMPL", - "role_spec": "role-specs/gongbu.md", - "responsibility": "功能开发、架构设计、代码实现、重构优化", - "inner_loop": true, - "message_types": ["impl_complete", "impl_progress", "error"] - }, - "bingbu": { - "alias": "兵部", - "task_prefix": "OPS", - "role_spec": "role-specs/bingbu.md", - "responsibility": "基础设施运维、部署发布、CI/CD、性能监控、安全防御", - "inner_loop": true, - "message_types": ["ops_complete", "ops_progress", "error"] - }, - "hubu": { - "alias": "户部", - "task_prefix": "DATA", - "role_spec": "role-specs/hubu.md", - "responsibility": "数据分析、统计汇总、成本分析、资源管理、报表生成", - "inner_loop": true, - "message_types": ["data_complete", "data_progress", "error"] - }, - "libu": { - "alias": "礼部", - "task_prefix": "DOC", - "role_spec": "role-specs/libu.md", - "responsibility": "文档撰写、规范制定、UI/UX文案、API文档、对外沟通", - "inner_loop": true, - "message_types": ["doc_complete", "doc_progress", "error"] - }, - "libu-hr": { - "alias": "吏部", - "task_prefix": "HR", - "role_spec": "role-specs/libu-hr.md", - "responsibility": "Agent管理、技能培训与优化、考核评估、协作规范制定", - "inner_loop": false, - "message_types": ["hr_complete", "error"] - }, - "xingbu": { - "alias": "刑部", - "task_prefix": "QA", - "role_spec": "role-specs/xingbu.md", - "responsibility": "代码审查、测试验收、Bug定位修复、合规审计（test-fix循环最多3轮）", - "inner_loop": true, - "message_types": ["qa_complete", "qa_progress", "fix_required", "error"] - } - }, - - "pipeline": { - "type": "cascade_with_parallel_execution", - "description": "串行审批链 + 六部按依赖并行执行", - "stages": [ - { - "stage": 1, - "name": "规划", - "roles": ["zhongshu"], - "blockedBy": [] - }, - { - "stage": 2, - "name": "审议", - "roles": ["menxia"], - "blockedBy": ["zhongshu"], - "retry": {"max_rounds": 3, "on_reject": "respawn zhongshu with feedback"} - }, - { - "stage": 3, - "name": "调度", - "roles": ["shangshu"], - "blockedBy": ["menxia"] - }, - { - "stage": 4, - "name": "执行", - "roles": ["gongbu", "bingbu", "hubu", "libu", "libu-hr", "xingbu"], - "blockedBy": ["shangshu"], - "parallel": true, - "note": "实际并行度由 dispatch-plan.md 中的 blockedBy 决定" - } - ], - "diagram": "PLAN-001 -> REVIEW-001 -> DISPATCH-001 -> [IMPL/OPS/DATA/DOC/HR/QA 按需并行]" - }, - - "kanban_protocol": { - "description": "所有 worker 强制遵守的看板状态上报规范", - "state_machine": ["Pending", "Doing", "Blocked", "Done"], - "mandatory_events": [ - {"event": "接任务时", "type": "state_update", "data": "state=Doing + current_step"}, - {"event": "每个关键步骤", "type": "impl_progress", "data": "current + plan(步骤1✅|步骤2🔄|步骤3)"}, - {"event": "完成时", "type": "task_handoff", "data": "from_role -> coordinator + remark"}, - {"event": "阻塞时", "type": "error", "data": "state=Blocked + reason"} - ], - "implementation": "team_msg(operation='log', session_id=, from=, ...)" - }, - - "routing_rules": { - "description": "尚书省六部路由规则", - "rules": [ - {"keywords": ["功能开发", "架构", "代码", "重构", "API", "接口", "实现"], "department": "gongbu"}, - {"keywords": ["部署", "CI/CD", "基础设施", "容器", "性能监控", "安全防御"], "department": "bingbu"}, - {"keywords": ["数据分析", "统计", "成本", "报表", "资源管理"], "department": "hubu"}, - {"keywords": ["文档", "README", "UI文案", "规范", "API文档", "对外沟通"], "department": "libu"}, - {"keywords": ["测试", "QA", "Bug", "审查", "合规审计"], "department": "xingbu"}, - {"keywords": ["Agent管理", "培训", "技能优化", "考核"], "department": "libu-hr"} - ] - }, - - "session_dirs": { - "base": ".workflow/.team/EDT-{slug}-{YYYY-MM-DD}/", - "plan": "plan/", - "review": "review/", - "artifacts": "artifacts/", - "kanban": "kanban/", - "wisdom": "wisdom/contributions/", - "messages": ".msg/" - }, - - "artifacts": { - "zhongshu": "plan/zhongshu-plan.md", - "menxia": "review/menxia-review.md", - "shangshu": "plan/dispatch-plan.md", - "gongbu": "artifacts/gongbu-output.md", - "bingbu": "artifacts/bingbu-output.md", - "hubu": "artifacts/hubu-output.md", - "libu": "artifacts/libu-output.md", - "libu-hr": "artifacts/libu-hr-output.md", - "xingbu": "artifacts/xingbu-report.md" - } -} diff --git a/.claude/skills/workflow-lite-execute/SKILL.md b/.claude/skills/workflow-lite-execute/SKILL.md index de943dcf..d13ea906 100644 --- a/.claude/skills/workflow-lite-execute/SKILL.md +++ b/.claude/skills/workflow-lite-execute/SKILL.md @@ -1,6 +1,6 @@ --- name: workflow-lite-execute -description: Lightweight execution engine - multi-mode input, task grouping, batch execution, code review, and project state sync +description: Lightweight execution engine - multi-mode input, task grouping, batch execution, chain to test-review allowed-tools: Skill, Agent, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep --- @@ -90,14 +90,14 @@ function selectExecutionOptions() { ] }, { - question: "Enable code review after execution?", - header: "Code Review", + question: "Review tool for test-review phase?", + header: "Review Tool (passed to lite-test-review)", multiSelect: false, options: [ - { label: "Skip", description: "No review" }, - { label: "Gemini Review", description: "Gemini CLI tool" }, - { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" }, - { label: "Agent Review", description: "Current agent review" } + { label: "Agent Review", description: "Agent review in test-review (default)" }, + { label: "Gemini Review", description: "Gemini CLI in test-review" }, + { label: "Codex Review", description: "Codex CLI in test-review" }, + { label: "Skip", description: "Skip review in test-review" } ] } ] @@ -367,52 +367,7 @@ ${(t.test?.success_metrics || []).length > 0 ? `**Success metrics**: ${t.test.su } ``` -### Step 4: Code Review (Optional) - -> **CHECKPOINT**: Verify Phase 2 review protocol is in active memory. If only a summary remains, re-read `phases/02-lite-execute.md` now. - -**Skip Condition**: Only run if `codeReviewTool !== "Skip"` - -**Review Criteria** (all tools use same standard): -- **Convergence Criteria**: Verify each criterion from task convergence.criteria -- **Test Checklist** (Medium/High): Check unit, integration, success_metrics from task test -- **Code Quality**: Analyze quality, identify issues, suggest improvements -- **Plan Alignment**: Validate implementation matches planned approach and risk mitigations - -**Shared Prompt Template**: -``` -PURPOSE: Code review for implemented changes against plan convergence criteria and test requirements -TASK: • Verify plan convergence criteria fulfillment • Check test requirements (unit, integration, success_metrics) • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence and risk mitigations -MODE: analysis -CONTEXT: @**/* @{plan.json} @{.task/*.json} [@{exploration.json}] | Memory: Review lite-execute changes against plan requirements including test checklist -EXPECTED: Quality assessment with: convergence criteria verification, test checklist validation, issue identification, recommendations. Explicitly check each convergence criterion and test item from .task/*.json. -CONSTRAINTS: Focus on plan convergence criteria, test requirements, and plan adherence | analysis=READ-ONLY -``` - -**Tool-Specific Execution** (apply shared prompt template above): - -| Tool | Command | Notes | -|------|---------|-------| -| Agent Review | Current agent reads plan.json + applies review criteria directly | No CLI call | -| Gemini Review | `ccw cli -p "[template]" --tool gemini --mode analysis` | Recommended | -| Qwen Review | `ccw cli -p "[template]" --tool qwen --mode analysis` | Alternative | -| Codex Review (A) | `ccw cli -p "[template]" --tool codex --mode review` | With prompt, for complex reviews | -| Codex Review (B) | `ccw cli --tool codex --mode review --uncommitted` | No prompt, quick review | - -> Codex: `-p` prompt and target flags (`--uncommitted`/`--base`/`--commit`) are **mutually exclusive**. - -**Multi-Round Review**: -```javascript -const reviewId = `${sessionId}-review` -const reviewResult = Bash(`ccw cli -p "[template]" --tool gemini --mode analysis --id ${reviewId}`) -if (hasUnresolvedIssues(reviewResult)) { - Bash(`ccw cli -p "Clarify concerns" --resume ${reviewId} --tool gemini --mode analysis --id ${reviewId}-followup`) -} -``` - -**Artifact Substitution**: Replace `@{plan.json}` → `@${executionContext.session.artifacts.plan}`, `[@{exploration.json}]` → exploration files from artifacts (if exists). - -### Step 5: Chain to Test Review & Post-Completion +### Step 4: Chain to Test Review & Post-Completion > **Note**: Spec sync (session:sync) is handled by lite-test-review's TR-Phase 5, not here. This avoids duplicate sync and ensures test fix changes are also captured. @@ -420,7 +375,7 @@ if (hasUnresolvedIssues(reviewResult)) { ```javascript function mapReviewTool(codeReviewTool) { - if (!codeReviewTool || codeReviewTool === 'Skip') return 'agent' + if (!codeReviewTool || codeReviewTool === 'Skip') return 'skip' if (/gemini/i.test(codeReviewTool)) return 'gemini' if (/codex/i.test(codeReviewTool)) return 'codex' return 'agent' diff --git a/.claude/skills/workflow-lite-plan/SKILL.md b/.claude/skills/workflow-lite-plan/SKILL.md index e6bf3406..b3bf9a18 100644 --- a/.claude/skills/workflow-lite-plan/SKILL.md +++ b/.claude/skills/workflow-lite-plan/SKILL.md @@ -94,9 +94,24 @@ TodoWrite({ todos: [ **Exploration Decision Logic**: ```javascript const hasPriorAnalysis = /##\s*Prior Analysis/i.test(task_description) +const hasHandoffSpec = /```json:handoff-spec/i.test(task_description) + +// Parse structured handoff from analyze-with-file (if present) +let handoffSpec = null +if (hasHandoffSpec) { + const specMatch = task_description.match(/```json:handoff-spec\s*\n([\s\S]*?)\n```/) + if (specMatch) { + handoffSpec = JSON.parse(specMatch[1]) + // handoffSpec contains: { source, session_id, session_folder, summary, + // implementation_scope[], code_anchors[], key_files[], key_findings[], decision_context[] } + // implementation_scope[]: { objective, rationale, priority, target_files[], acceptance_criteria[], change_summary } + console.log(`[Handoff] From ${handoffSpec.source} session ${handoffSpec.session_id}`) + console.log(`[Handoff] ${handoffSpec.implementation_scope.length} scoped items with acceptance criteria`) + } +} needsExploration = workflowPreferences.forceExplore ? true - : hasPriorAnalysis ? false + : (hasPriorAnalysis || hasHandoffSpec) ? false : (task.mentions_specific_files || task.requires_codebase_context || task.needs_architecture_understanding || @@ -104,6 +119,7 @@ needsExploration = workflowPreferences.forceExplore ? true if (!needsExploration) { // manifest absent; LP-Phase 3 loads with safe fallback + // If handoffSpec exists, it provides pre-scoped implementation context proceed_to_next_phase() } ``` @@ -323,13 +339,26 @@ manifest.explorations.forEach(exp => { console.log(`\n### Exploration: ${exp.angle}\n${Read(exp.path)}`) }) -// Generate tasks — MUST incorporate exploration insights +// When handoffSpec exists, use it as primary planning input +// implementation_scope[].acceptance_criteria -> convergence.criteria +// implementation_scope[].target_files -> files[] +// implementation_scope[].objective -> task title/description +if (handoffSpec) { + console.log(`\n### Handoff Spec from ${handoffSpec.source}`) + console.log(`Scope items: ${handoffSpec.implementation_scope.length}`) + handoffSpec.implementation_scope.forEach((item, i) => { + console.log(` ${i+1}. ${item.objective} [${item.priority}] — Done when: ${item.acceptance_criteria.join('; ')}`) + }) +} + +// Generate tasks — MUST incorporate exploration insights OR handoff spec +// When handoffSpec: map implementation_scope[] → tasks[] (1:1 or group by context) // Field names: convergence.criteria (not acceptance), files[].change (not modification_points), test (not verification) const tasks = [ { id: "TASK-001", title: "...", description: "...", depends_on: [], - convergence: { criteria: ["..."] }, - files: [{ path: "...", change: "..." }], + convergence: { criteria: ["..."] }, // From handoffSpec: item.acceptance_criteria + files: [{ path: "...", change: "..." }], // From handoffSpec: item.target_files + item.change_summary implementation: ["..."], test: "..." } ] @@ -386,6 +415,28 @@ Total: ${manifest.exploration_count} | Angles: ${manifest.explorations.map(e => Manifest: ${sessionFolder}/explorations-manifest.json` : `No exploration files. Task Description contains "## Prior Analysis" — use as primary planning context.`} +## Structured Handoff Spec (from analyze-with-file) +${handoffSpec ? ` +**Source**: ${handoffSpec.source} session ${handoffSpec.session_id} +**CRITICAL**: Use implementation_scope as PRIMARY input for task generation. +Each scope item maps to one or more tasks. Acceptance criteria become convergence.criteria. + +${JSON.stringify(handoffSpec.implementation_scope, null, 2)} + +**Code Anchors** (implementation targets): +${JSON.stringify(handoffSpec.code_anchors?.slice(0, 8), null, 2)} + +**Key Findings** (context): +${JSON.stringify(handoffSpec.key_findings?.slice(0, 5), null, 2)} + +**Task Generation Rules when handoffSpec present**: +1. Each implementation_scope item → 1 task (group only if tightly coupled) +2. scope.acceptance_criteria[] → task.convergence.criteria[] +3. scope.target_files[] → task.files[] with change from scope.change_summary +4. scope.objective → task.title, scope.rationale → task.description context +5. scope.priority → task ordering (high first) +` : 'No structured handoff spec — use task description and explorations as input.'} + ## User Clarifications ${JSON.stringify(clarificationContext) || "None"} diff --git a/.claude/skills/workflow-lite-test-review/SKILL.md b/.claude/skills/workflow-lite-test-review/SKILL.md index 54060a1e..6c0d364c 100644 --- a/.claude/skills/workflow-lite-test-review/SKILL.md +++ b/.claude/skills/workflow-lite-test-review/SKILL.md @@ -27,20 +27,19 @@ Test review and fix engine for lite-execute chain or standalone invocation. **Trigger**: `--in-memory` flag or `testReviewContext` global variable available -**Input Source**: `testReviewContext` global variable set by lite-execute Step 6 +**Input Source**: `testReviewContext` global variable set by lite-execute Step 4 -**Behavior**: Skip session discovery (already resolved), inherit review tool from execution chain, proceed directly to TR-Phase 1. +**Behavior**: Skip session discovery, inherit reviewTool from execution chain, proceed directly to TR-Phase 1. -> **Note**: lite-execute Step 6 is the chain gate. Mode 1 invocation means execution is complete — proceed with test review. +> **Note**: lite-execute Step 4 is the chain gate. Mode 1 invocation means execution is complete — proceed with test review. ### Mode 2: Standalone **Trigger**: User calls with session path or `--last` -**Behavior**: Discover session → load plan + tasks → detect test tool → proceed to TR-Phase 1. +**Behavior**: Discover session → load plan + tasks → `reviewTool = 'agent'` → proceed to TR-Phase 1. ```javascript -// Session discovery let sessionPath, plan, taskFiles, reviewTool if (testReviewContext) { @@ -50,21 +49,11 @@ if (testReviewContext) { taskFiles = testReviewContext.taskFiles.map(tf => JSON.parse(Read(tf.path))) reviewTool = testReviewContext.reviewTool || 'agent' } else { - // Mode 2: standalone - const args = $ARGUMENTS - if (args.includes('--last') || !args.trim() || args.trim() === '--skip-fix') { - const sessions = Glob('.workflow/.lite-plan/*/plan.json') - if (sessions.length === 0) { - console.error('No lite-plan sessions found.') - return - } - sessionPath = sessions[sessions.length - 1].replace(/[/\\]plan\.json$/, '') - } else { - sessionPath = args.replace(/--skip-fix|--last/g, '').trim() - } + // Mode 2: standalone — find last session or use provided path + sessionPath = resolveSessionPath($ARGUMENTS) // Glob('.workflow/.lite-plan/*/plan.json'), take last plan = JSON.parse(Read(`${sessionPath}/plan.json`)) taskFiles = plan.task_ids.map(id => JSON.parse(Read(`${sessionPath}/.task/${id}.json`))) - reviewTool = 'agent' // default for standalone + reviewTool = 'agent' } const skipFix = $ARGUMENTS?.includes('--skip-fix') || false @@ -74,7 +63,7 @@ const skipFix = $ARGUMENTS?.includes('--skip-fix') || false | Phase | Core Action | Output | |-------|-------------|--------| -| TR-Phase 1 | Detect test framework + gather changes | testConfig | +| TR-Phase 1 | Detect test framework + gather changes | testConfig, changedFiles | | TR-Phase 2 | Review implementation against convergence criteria | reviewResults[] | | TR-Phase 3 | Run tests + generate checklist | test-checklist.json | | TR-Phase 4 | Auto-fix failures (iterative, max 3 rounds) | Fixed code + updated checklist | @@ -82,180 +71,68 @@ const skipFix = $ARGUMENTS?.includes('--skip-fix') || false ## TR-Phase 0: Initialize -```javascript -const sessionId = sessionPath.split('/').pop() - -TodoWrite({ todos: [ - { content: "TR-Phase 1: Detect & Gather", status: "in_progress", activeForm: "Detecting test framework" }, - { content: "TR-Phase 2: Review Convergence", status: "pending" }, - { content: "TR-Phase 3: Run Tests", status: "pending" }, - { content: "TR-Phase 4: Auto-Fix", status: "pending" }, - { content: "TR-Phase 5: Report & Sync", status: "pending" } -]}) -``` +Set `sessionId` from sessionPath. Create TodoWrite with 5 phases (Phase 1 = in_progress, rest = pending). ## TR-Phase 1: Detect Test Framework & Gather Changes -```javascript -// Detect test framework -const hasPackageJson = Glob('package.json').length > 0 -const hasPyproject = Glob('pyproject.toml').length > 0 -const hasCargo = Glob('Cargo.toml').length > 0 -const hasGoMod = Glob('go.mod').length > 0 +**Test framework detection** (check in order, first match wins): -let testConfig = { command: null, framework: null, type: null } +| File | Framework | Command | +|------|-----------|---------| +| `package.json` with `scripts.test` | jest/vitest | `npm test` | +| `package.json` with `scripts['test:unit']` | jest/vitest | `npm run test:unit` | +| `pyproject.toml` | pytest | `python -m pytest -v --tb=short` | +| `Cargo.toml` | cargo-test | `cargo test` | +| `go.mod` | go-test | `go test ./...` | -if (hasPackageJson) { - const pkg = JSON.parse(Read('package.json')) - const scripts = pkg.scripts || {} - if (scripts.test) { testConfig = { command: 'npm test', framework: 'jest/vitest', type: 'node' } } - else if (scripts['test:unit']) { testConfig = { command: 'npm run test:unit', framework: 'jest/vitest', type: 'node' } } -} else if (hasPyproject) { - testConfig = { command: 'python -m pytest -v --tb=short', framework: 'pytest', type: 'python' } -} else if (hasCargo) { - testConfig = { command: 'cargo test', framework: 'cargo-test', type: 'rust' } -} else if (hasGoMod) { - testConfig = { command: 'go test ./...', framework: 'go-test', type: 'go' } -} +**Gather git changes**: `git diff --name-only HEAD~5..HEAD` → `changedFiles[]` -// Gather git changes -const changedFiles = Bash('git diff --name-only HEAD~5..HEAD 2>/dev/null || git diff --name-only HEAD') - .split('\n').filter(Boolean) -const gitDiffStat = Bash('git diff --stat HEAD~5..HEAD 2>/dev/null || git diff --stat HEAD') - -console.log(`Test Framework: ${testConfig.framework || 'unknown'} | Command: ${testConfig.command || 'none'}`) -console.log(`Changed Files: ${changedFiles.length}`) -``` +Output: `testConfig = { command, framework, type }` + `changedFiles[]` // TodoWrite: Phase 1 → completed, Phase 2 → in_progress ## TR-Phase 2: Review Implementation Against Plan -For each task, verify convergence criteria using agent or CLI review tool. +**Skip if**: `reviewTool === 'skip'` — set all tasks to PASS, proceed to Phase 3. + +For each task, verify convergence criteria and identify test gaps. **Agent Review** (reviewTool === 'agent', default): -```javascript -const reviewResults = [] - -for (const task of taskFiles) { - const criteria = task.convergence?.criteria || [] - const testReqs = task.test || {} - - // Find actual changed files matching task scope - const taskTargetFiles = (task.files || []) - .map(f => f.path) - .filter(p => changedFiles.some(c => c.includes(p) || p.includes(c))) - - // Read implementation to verify criteria - const fileContents = taskTargetFiles.map(p => { - try { return { path: p, content: Read(p) } } - catch { return { path: p, content: null } } - }).filter(f => f.content) - - const review = { - taskId: task.id, - title: task.title, - criteria_met: [], - criteria_unmet: [], - test_gaps: [], - files_reviewed: taskTargetFiles - } - - // Agent evaluates each criterion against file contents - for (const criterion of criteria) { - // Check: does implementation satisfy this criterion? - // Analyze file contents, look for expected patterns/functions/logic - const met = /* agent evaluation based on fileContents */ true_or_false - if (met) review.criteria_met.push(criterion) - else review.criteria_unmet.push(criterion) - } - - // Check test coverage gaps - const hasTestFiles = changedFiles.some(f => - /test[_\-.]|spec[_\-.]|\/__tests__\/|\/tests\//.test(f) - ) - if (testReqs.unit?.length > 0 && !hasTestFiles) { - testReqs.unit.forEach(u => review.test_gaps.push({ type: 'unit', desc: u })) - } - if (testReqs.integration?.length > 0) { - testReqs.integration.forEach(i => review.test_gaps.push({ type: 'integration', desc: i })) - } - - reviewResults.push(review) -} -``` +For each task in taskFiles: +1. Extract `convergence.criteria[]` and `test` requirements +2. Find changed files matching `task.files[].path` against `changedFiles` +3. Read matched files, evaluate each criterion against implementation +4. Check test coverage: if `task.test.unit` exists but no test files in changedFiles → mark as test gap +5. Same for `task.test.integration` +6. Build `reviewResult = { taskId, title, criteria_met[], criteria_unmet[], test_gaps[], files_reviewed[] }` **CLI Review** (reviewTool === 'gemini' or 'codex'): ```javascript -if (reviewTool !== 'agent') { - const reviewId = `${sessionId}-tr-review` - Bash(`ccw cli -p "PURPOSE: Post-execution test review — verify convergence criteria met and identify test gaps +const reviewId = `${sessionId}-tr-review` +Bash(`ccw cli -p "PURPOSE: Post-execution test review — verify convergence criteria met and identify test gaps TASK: • Read plan.json and .task/*.json convergence criteria • For each criterion, check implementation in changed files • Identify missing unit/integration tests • List unmet criteria with file:line evidence MODE: analysis CONTEXT: @${sessionPath}/plan.json @${sessionPath}/.task/*.json @**/* | Memory: lite-execute completed, reviewing convergence EXPECTED: Per-task verdict table (PASS/PARTIAL/FAIL) + unmet criteria list + test gap list CONSTRAINTS: Read-only | Focus on convergence verification" --tool ${reviewTool} --mode analysis --id ${reviewId}`, { run_in_background: true }) - // STOP - wait for hook callback, then parse CLI output into reviewResults format -} +// STOP - wait for hook callback, then parse CLI output into reviewResults format ``` // TodoWrite: Phase 2 → completed, Phase 3 → in_progress ## TR-Phase 3: Run Tests & Generate Checklist -```javascript -// Build checklist structure -const testChecklist = { - session: sessionId, - plan_summary: plan.summary, - generated_at: new Date().toISOString(), - test_config: testConfig, - tasks: reviewResults.map(review => { - const task = taskFiles.find(t => t.id === review.taskId) - const testReqs = task.test || {} - return { - task_id: review.taskId, - title: review.title, - status: review.criteria_unmet.length === 0 ? 'PASS' - : review.criteria_met.length > 0 ? 'PARTIAL' : 'FAIL', - convergence: { met: review.criteria_met, unmet: review.criteria_unmet }, - test_items: [ - ...(testReqs.unit || []).map(u => ({ type: 'unit', desc: u, status: 'pending' })), - ...(testReqs.integration || []).map(i => ({ type: 'integration', desc: i, status: 'pending' })), - ...(testReqs.success_metrics || []).map(m => ({ type: 'metric', desc: m, status: 'pending' })), - ...review.test_gaps.map(g => ({ type: g.type, desc: g.desc, status: 'missing' })) - ] - } - }), - execution: null -} +**Build checklist** from reviewResults: +- Per task: status = `PASS` (all criteria met) / `PARTIAL` (some met) / `FAIL` (none met) +- Collect test_items from `task.test.unit[]`, `task.test.integration[]`, `task.test.success_metrics[]` + review test_gaps -// Run tests if framework detected -if (testConfig.command) { - console.log(`Running: ${testConfig.command}`) - const testResult = Bash(testConfig.command, { timeout: 300000 }) +**Run tests** if `testConfig.command` exists: +- Execute with 5min timeout +- Parse output: detect passed/failed patterns → `overall: 'PASS' | 'FAIL' | 'UNKNOWN'` - const passed = /(\d+) passed/.test(testResult) || /PASSED/.test(testResult) || /ok \d+/.test(testResult) - const failMatch = testResult.match(/(\d+) failed/) - const hasFail = failMatch || /FAILED/.test(testResult) || /FAIL/.test(testResult) - - testChecklist.execution = { - command: testConfig.command, - timestamp: new Date().toISOString(), - raw_output: testResult.slice(-3000), // keep tail for error context - overall: hasFail ? 'FAIL' : (passed ? 'PASS' : 'UNKNOWN'), - fail_count: failMatch ? parseInt(failMatch[1]) : (hasFail ? -1 : 0) - } - - console.log(`Result: ${testChecklist.execution.overall}`) -} else { - console.log('No test command detected. Skipping test execution.') -} - -Write(`${sessionPath}/test-checklist.json`, JSON.stringify(testChecklist, null, 2)) -``` +**Write** `${sessionPath}/test-checklist.json` // TodoWrite: Phase 3 → completed, Phase 4 → in_progress @@ -263,28 +140,16 @@ Write(`${sessionPath}/test-checklist.json`, JSON.stringify(testChecklist, null, **Skip if**: `skipFix === true` OR `testChecklist.execution?.overall !== 'FAIL'` -**Max iterations**: 3 +**Max iterations**: 3. Each iteration: + +1. Delegate to test-fix-agent: ```javascript -if (skipFix || !testChecklist.execution || testChecklist.execution.overall !== 'FAIL') { - console.log(testChecklist.execution?.overall === 'PASS' - ? 'All tests passed. Skipping fix phase.' - : 'Skipping auto-fix (--skip-fix or no test execution).') - // TodoWrite: Phase 4 → completed (skipped) -} else { - let iteration = 0 - const MAX_ITERATIONS = 3 - - while (iteration < MAX_ITERATIONS && testChecklist.execution.overall === 'FAIL') { - iteration++ - console.log(`\n--- Fix Iteration ${iteration}/${MAX_ITERATIONS} ---`) - - // Use test-fix-agent for fixing - Agent({ - subagent_type: "test-fix-agent", - run_in_background: false, - description: `Fix tests (iter ${iteration})`, - prompt: `## Test Fix Iteration ${iteration}/${MAX_ITERATIONS} +Agent({ + subagent_type: "test-fix-agent", + run_in_background: false, + description: `Fix tests (iter ${iteration})`, + prompt: `## Test Fix Iteration ${iteration}/${MAX_ITERATIONS} **Test Command**: ${testConfig.command} **Framework**: ${testConfig.framework} @@ -305,98 +170,38 @@ ${testChecklist.execution.raw_output} 3. Run \`${testConfig.command}\` to verify fix 4. If fix introduces new failures, revert and try alternative approach 5. Return: what was fixed, which files changed, test result after fix` - }) - - // Re-run tests after fix - const retestResult = Bash(testConfig.command, { timeout: 300000 }) - const hasFail = /failed|FAIL/.test(retestResult) - - testChecklist.execution = { - command: testConfig.command, - timestamp: new Date().toISOString(), - raw_output: retestResult.slice(-3000), - overall: hasFail ? 'FAIL' : 'PASS', - fix_iteration: iteration - } - - Write(`${sessionPath}/test-checklist.json`, JSON.stringify(testChecklist, null, 2)) - - if (!hasFail) { - console.log(`Tests passed after iteration ${iteration}.`) - break - } - } - - if (testChecklist.execution.overall === 'FAIL') { - console.log(`Tests still failing after ${MAX_ITERATIONS} iterations. Manual investigation needed.`) - } -} +}) ``` +2. Re-run `testConfig.command` → update `testChecklist.execution` +3. Write updated `test-checklist.json` +4. Break if tests pass; continue if still failing + +If still failing after 3 iterations → log "Manual investigation needed" + // TodoWrite: Phase 4 → completed, Phase 5 → in_progress ## TR-Phase 5: Report & Sync > **CHECKPOINT**: This step is MANDATORY. Always generate report and trigger sync. +**Generate `test-review.md`** with sections: +- Header: session, summary, timestamp, framework +- **Task Verdicts** table: task_id | status | convergence (met/total) | test_items | gaps +- **Unmet Criteria**: per-task checklist of unmet items +- **Test Gaps**: list of missing unit/integration tests +- **Test Execution**: command, result, fix iteration (if applicable) + +**Write** `${sessionPath}/test-review.md` + +**Chain to session:sync**: ```javascript -// Generate markdown report -const report = `# Test Review Report - -**Session**: ${sessionId} -**Summary**: ${plan.summary} -**Generated**: ${new Date().toISOString()} -**Test Framework**: ${testConfig.framework || 'unknown'} - -## Task Verdicts - -| Task | Status | Convergence | Test Items | Gaps | -|------|--------|-------------|------------|------| -${testChecklist.tasks.map(t => - `| ${t.task_id} | ${t.status} | ${t.convergence.met.length}/${t.convergence.met.length + t.convergence.unmet.length} | ${t.test_items.length} | ${t.test_items.filter(i => i.status === 'missing').length} |` -).join('\n')} - -## Unmet Criteria - -${testChecklist.tasks.filter(t => t.convergence.unmet.length > 0).map(t => - `### ${t.task_id}: ${t.title}\n${t.convergence.unmet.map(u => \`- [ ] \${u}\`).join('\n')}` -).join('\n\n') || 'All criteria met.'} - -## Test Gaps - -${testChecklist.tasks.flatMap(t => t.test_items.filter(i => i.status === 'missing')).map(i => - \`- [ ] (\${i.type}) \${i.desc}\` -).join('\n') || 'No gaps detected.'} - -${testChecklist.execution ? `## Test Execution - -**Command**: \\\`${testChecklist.execution.command}\\\` -**Result**: ${testChecklist.execution.overall} -${testChecklist.execution.fix_iteration ? `**Fixed in iteration**: ${testChecklist.execution.fix_iteration}` : ''} -` : '## Test Execution\n\nNo test framework detected.'} -` - -Write(`${sessionPath}/test-review.md`, report) -console.log(`Report: ${sessionPath}/test-review.md`) -console.log(`Checklist: ${sessionPath}/test-checklist.json`) - -// Chain to session:sync Skill({ skill: "workflow:session:sync", args: `-y "Test review: ${testChecklist.execution?.overall || 'no-test'} — ${plan.summary}"` }) ``` // TodoWrite: Phase 5 → completed -**Display summary**: -```javascript -console.log(` -── Test Review Complete ── -${testChecklist.tasks.map(t => { - const icon = t.status === 'PASS' ? '[PASS]' : t.status === 'PARTIAL' ? '[PARTIAL]' : '[FAIL]' - return `${icon} ${t.task_id}: ${t.title} (${t.convergence.met.length}/${t.convergence.met.length + t.convergence.unmet.length})` -}).join('\n')} -Test: ${testChecklist.execution?.overall || 'skipped'}${testChecklist.execution?.fix_iteration ? ` (fixed iter ${testChecklist.execution.fix_iteration})` : ''} -`) -``` +**Display summary**: Per-task verdict with [PASS]/[PARTIAL]/[FAIL] icons, convergence ratio, overall test result. ## Data Structures @@ -406,8 +211,8 @@ Test: ${testChecklist.execution?.overall || 'skipped'}${testChecklist.execution? { planObject: { /* same as executionContext.planObject */ }, taskFiles: [{ id: string, path: string }], - reviewTool: "agent" | "gemini" | "codex", // inherited from lite-execute codeReviewTool - executionResults: [...], // previousExecutionResults from lite-execute + reviewTool: "skip" | "agent" | "gemini" | "codex", + executionResults: [...], originalUserInput: string, session: { id: string, @@ -417,6 +222,31 @@ Test: ${testChecklist.execution?.overall || 'skipped'}${testChecklist.execution? } ``` +### testChecklist (Output artifact) + +```javascript +{ + session: string, + plan_summary: string, + generated_at: string, + test_config: { command, framework, type }, + tasks: [{ + task_id: string, + title: string, + status: "PASS" | "PARTIAL" | "FAIL", + convergence: { met: string[], unmet: string[] }, + test_items: [{ type: "unit"|"integration"|"metric", desc: string, status: "pending"|"missing" }] + }], + execution: { + command: string, + timestamp: string, + raw_output: string, // last 3000 chars + overall: "PASS" | "FAIL" | "UNKNOWN", + fix_iteration?: number + } | null +} +``` + ## Session Folder Structure (after test-review) ``` @@ -426,8 +256,8 @@ Test: ${testChecklist.execution?.overall || 'skipped'}${testChecklist.execution? ├── planning-context.md ├── plan.json ├── .task/TASK-*.json -├── test-checklist.json # NEW: structured test results -└── test-review.md # NEW: human-readable report +├── test-checklist.json # structured test results +└── test-review.md # human-readable report ``` ## Error Handling diff --git a/.codex/skills/team-edict/SKILL.md b/.codex/skills/team-edict/SKILL.md deleted file mode 100644 index 85d221af..00000000 --- a/.codex/skills/team-edict/SKILL.md +++ /dev/null @@ -1,781 +0,0 @@ ---- -name: team-edict -description: | - 三省六部 multi-agent collaboration framework. Imperial edict workflow: - Crown Prince receives edict -> Zhongshu (Planning) -> Menxia (Multi-dimensional Review) -> - Shangshu (Dispatch) -> Six Ministries parallel execution. - Mandatory kanban state reporting, Blocked as first-class state, full observability. -argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"task description / edict\"" -allowed-tools: spawn_agents_on_csv, spawn_agent, wait, send_input, close_agent, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion ---- - -## Auto Mode - -When `--yes` or `-y`: Auto-confirm task decomposition, skip interactive validation, use defaults. - -# Team Edict -- Three Departments Six Ministries - -## Usage - -```bash -$team-edict "Implement user authentication module with JWT tokens" -$team-edict -c 4 "Refactor the data pipeline for better performance" -$team-edict -y "Add comprehensive test coverage for auth module" -$team-edict --continue "EDT-20260308-143022" -``` - -**Flags**: -- `-y, --yes`: Skip all confirmations (auto mode) -- `-c, --concurrency N`: Max concurrent agents within each wave (default: 4) -- `--continue`: Resume existing session - -**Output Directory**: `.workflow/.csv-wave/{session-id}/` -**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) - ---- - -## Overview - -Imperial edict-inspired multi-agent collaboration framework with **strict cascading approval pipeline** and **parallel ministry execution**. The Three Departments (zhongshu/menxia/shangshu) perform serial planning, review, and dispatch. The Six Ministries (gongbu/bingbu/hubu/libu/libu-hr/xingbu) execute tasks in dependency-ordered waves. - -**Execution Model**: Hybrid -- CSV wave pipeline (primary) + individual agent spawn (secondary) - -``` -+-------------------------------------------------------------------------+ -| TEAM EDICT WORKFLOW | -+-------------------------------------------------------------------------+ -| | -| Phase 0: Pre-Wave Interactive (Three Departments Serial Pipeline) | -| +-- Stage 1: Zhongshu (Planning) -- drafts execution plan | -| +-- Stage 2: Menxia (Review) -- multi-dimensional review | -| | +-- Reject -> loop back to Zhongshu (max 3 rounds) | -| +-- Stage 3: Shangshu (Dispatch) -- routes to Six Ministries | -| +-- Output: tasks.csv with ministry assignments + dependency waves | -| | -| Phase 1: Requirement -> CSV + Classification | -| +-- Parse Shangshu dispatch plan into tasks.csv | -| +-- Classify tasks: csv-wave (ministry work) | interactive (QA loop) | -| +-- Compute dependency waves (topological sort) | -| +-- Generate tasks.csv with wave + exec_mode columns | -| +-- User validates task breakdown (skip if -y) | -| | -| Phase 2: Wave Execution Engine (Extended) | -| +-- For each wave (1..N): | -| | +-- Build wave CSV (filter csv-wave tasks for this wave) | -| | +-- Inject previous findings into prev_context column | -| | +-- spawn_agents_on_csv(wave CSV) | -| | +-- Execute post-wave interactive tasks (if any) | -| | +-- Merge all results into master tasks.csv | -| | +-- Check: any failed? -> skip dependents | -| +-- discoveries.ndjson shared across all modes (append-only) | -| | -| Phase 3: Post-Wave Interactive (Quality Aggregation) | -| +-- Aggregation Agent: collects all ministry outputs | -| +-- Generates final edict completion report | -| +-- Quality gate validation against specs/quality-gates.md | -| | -| Phase 4: Results Aggregation | -| +-- Export final results.csv | -| +-- Generate context.md with all findings | -| +-- Display summary: completed/failed/skipped per wave | -| +-- Offer: view results | retry failed | done | -| | -+-------------------------------------------------------------------------+ -``` - ---- - -## Task Classification Rules - -Each task is classified by `exec_mode`: - -| exec_mode | Mechanism | Criteria | -|-----------|-----------|----------| -| `csv-wave` | `spawn_agents_on_csv` | One-shot, structured I/O, no multi-round interaction | -| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round, clarification, inline utility | - -**Classification Decision**: - -| Task Property | Classification | -|---------------|---------------| -| Ministry implementation (IMPL/OPS/DATA/DOC/HR) | `csv-wave` | -| Quality assurance with test-fix loop (QA) | `interactive` | -| Single-department self-contained work | `csv-wave` | -| Cross-department coordination needed | `interactive` | -| Requires iterative feedback (test -> fix -> retest) | `interactive` | -| Standalone analysis or generation | `csv-wave` | - ---- - -## CSV Schema - -### tasks.csv (Master State) - -```csv -id,title,description,deps,context_from,exec_mode,department,task_prefix,priority,dispatch_batch,acceptance_criteria,wave,status,findings,artifact_path,error -IMPL-001,"Implement JWT auth","Create JWT authentication middleware with token validation","","","csv-wave","gongbu","IMPL","P0","1","All auth endpoints return valid JWT tokens","1","pending","","","" -DOC-001,"Write API docs","Generate OpenAPI documentation for auth endpoints","IMPL-001","IMPL-001","csv-wave","libu","DOC","P1","2","API docs cover all auth endpoints","2","pending","","","" -QA-001,"Test auth module","Execute test suite and validate coverage >= 95%","IMPL-001","IMPL-001","interactive","xingbu","QA","P1","2","Test pass rate >= 95%, no Critical bugs","2","pending","","","" -``` - -**Columns**: - -| Column | Phase | Description | -|--------|-------|-------------| -| `id` | Input | Unique task identifier (DEPT-NNN format) | -| `title` | Input | Short task title | -| `description` | Input | Detailed task description (self-contained for agent execution) | -| `deps` | Input | Semicolon-separated dependency task IDs | -| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs | -| `exec_mode` | Input | `csv-wave` or `interactive` | -| `department` | Input | Target ministry: gongbu/bingbu/hubu/libu/libu-hr/xingbu | -| `task_prefix` | Input | Task type prefix: IMPL/OPS/DATA/DOC/HR/QA | -| `priority` | Input | Priority level: P0 (highest) to P3 (lowest) | -| `dispatch_batch` | Input | Batch number from Shangshu dispatch plan (1-based) | -| `acceptance_criteria` | Input | Specific, measurable acceptance criteria from dispatch plan | -| `wave` | Computed | Wave number (computed by topological sort, 1-based) | -| `status` | Output | `pending` -> `completed` / `failed` / `skipped` | -| `findings` | Output | Key discoveries or implementation notes (max 500 chars) | -| `artifact_path` | Output | Path to output artifact file relative to session dir | -| `error` | Output | Error message if failed (empty if success) | - -### Per-Wave CSV (Temporary) - -Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column (csv-wave tasks only). - ---- - -## Agent Registry (Interactive Agents) - -| Agent | Role File | Pattern | Responsibility | Position | -|-------|-----------|---------|----------------|----------| -| zhongshu-planner | agents/zhongshu-planner.md | 2.3 (sequential pipeline) | Draft structured execution plan from edict requirements | standalone (Phase 0, Stage 1) | -| menxia-reviewer | agents/menxia-reviewer.md | 2.4 (multi-perspective analysis) | Multi-dimensional review with 4 CLI analyses | standalone (Phase 0, Stage 2) | -| shangshu-dispatcher | agents/shangshu-dispatcher.md | 2.3 (sequential pipeline) | Parse approved plan and generate ministry task assignments | standalone (Phase 0, Stage 3) | -| qa-verifier | agents/qa-verifier.md | 2.5 (iterative refinement) | Quality assurance with test-fix loop (max 3 rounds) | post-wave | -| aggregator | agents/aggregator.md | 2.3 (sequential pipeline) | Collect all ministry outputs and generate final report | standalone (Phase 3) | - -> **COMPACT PROTECTION**: Agent files are execution documents. When context compression occurs, **you MUST immediately `Read` the corresponding agent.md** to reload. - ---- - -## Output Artifacts - -| File | Purpose | Lifecycle | -|------|---------|-----------| -| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave | -| `wave-{N}.csv` | Per-wave input (temporary, csv-wave tasks only) | Created before wave, deleted after | -| `results.csv` | Final export of all task results | Created in Phase 4 | -| `discoveries.ndjson` | Shared exploration board (all agents, both modes) | Append-only, carries across waves | -| `context.md` | Human-readable execution report | Created in Phase 4 | -| `plan/zhongshu-plan.md` | Zhongshu execution plan | Created in Phase 0 Stage 1 | -| `review/menxia-review.md` | Menxia review report with 4-dimensional analysis | Created in Phase 0 Stage 2 | -| `plan/dispatch-plan.md` | Shangshu dispatch plan with ministry assignments | Created in Phase 0 Stage 3 | -| `artifacts/{dept}-output.md` | Per-ministry output artifact | Created during wave execution | -| `interactive/{id}-result.json` | Results from interactive tasks (QA loops) | Created per interactive task | -| `agents/registry.json` | Active interactive agent tracking | Updated on spawn/close | - ---- - -## Session Structure - -``` -.workflow/.csv-wave/{session-id}/ -+-- tasks.csv # Master state (all tasks, both modes) -+-- results.csv # Final results export -+-- discoveries.ndjson # Shared discovery board (all agents) -+-- context.md # Human-readable report -+-- wave-{N}.csv # Temporary per-wave input (csv-wave only) -+-- plan/ -| +-- zhongshu-plan.md # Zhongshu execution plan -| +-- dispatch-plan.md # Shangshu dispatch plan -+-- review/ -| +-- menxia-review.md # Menxia review report -+-- artifacts/ -| +-- gongbu-output.md # Ministry outputs -| +-- bingbu-output.md -| +-- hubu-output.md -| +-- libu-output.md -| +-- libu-hr-output.md -| +-- xingbu-report.md -+-- interactive/ # Interactive task artifacts -| +-- {id}-result.json # Per-task results -+-- agents/ - +-- registry.json # Active interactive agent tracking -``` - ---- - -## Implementation - -### Session Initialization - -``` -1. Parse $ARGUMENTS for task description (the "edict") -2. Generate session ID: EDT-{slug}-{YYYYMMDD-HHmmss} -3. Create session directory: .workflow/.csv-wave/{session-id}/ -4. Create subdirectories: plan/, review/, artifacts/, interactive/, agents/ -5. Initialize registry.json: { "active": [], "closed": [] } -6. Initialize discoveries.ndjson (empty file) -7. Read specs: ~ or /.codex/skills/team-edict/specs/team-config.json -8. Read quality gates: ~ or /.codex/skills/team-edict/specs/quality-gates.md -9. Log session start to context.md -``` - ---- - -### Phase 0: Pre-Wave Interactive (Three Departments Serial Pipeline) - -**Objective**: Execute the serial approval pipeline (zhongshu -> menxia -> shangshu) to produce a validated, reviewed dispatch plan that decomposes the edict into ministry-level tasks. - -#### Stage 1: Zhongshu Planning - -```javascript -const zhongshu = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~ or /.codex/skills/team-edict/agents/zhongshu-planner.md (MUST read first) -2. Read: ${sessionDir}/discoveries.ndjson (shared discoveries, skip if not exists) -3. Read: ~ or /.codex/skills/team-edict/specs/team-config.json (routing rules) - ---- - -Goal: Draft a structured execution plan for the following edict -Scope: Analyze codebase, decompose into ministry-level subtasks, define acceptance criteria -Deliverables: ${sessionDir}/plan/zhongshu-plan.md - -### Edict (Original Requirement) -${edictText} -` -}) - -const zhongshuResult = wait({ ids: [zhongshu], timeout_ms: 600000 }) - -if (zhongshuResult.timed_out) { - send_input({ id: zhongshu, message: "Please finalize your execution plan immediately and output current findings." }) - const retry = wait({ ids: [zhongshu], timeout_ms: 120000 }) -} - -// Store result -Write(`${sessionDir}/interactive/zhongshu-result.json`, JSON.stringify({ - task_id: "PLAN-001", - status: "completed", - findings: parseFindings(zhongshuResult), - timestamp: new Date().toISOString() -})) - -close_agent({ id: zhongshu }) -``` - -#### Stage 2: Menxia Multi-Dimensional Review - -**Rejection Loop**: If menxia rejects (approved=false), respawn zhongshu with feedback. Max 3 rounds. - -```javascript -let reviewRound = 0 -let approved = false - -while (!approved && reviewRound < 3) { - reviewRound++ - - const menxia = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~ or /.codex/skills/team-edict/agents/menxia-reviewer.md (MUST read first) -2. Read: ${sessionDir}/plan/zhongshu-plan.md (plan to review) -3. Read: ${sessionDir}/discoveries.ndjson (shared discoveries) - ---- - -Goal: Multi-dimensional review of Zhongshu plan (Round ${reviewRound}/3) -Scope: Feasibility, completeness, risk, resource allocation -Deliverables: ${sessionDir}/review/menxia-review.md - -### Original Edict -${edictText} - -### Previous Review (if rejection round > 1) -${reviewRound > 1 ? readPreviousReview() : "First review round"} -` - }) - - const menxiaResult = wait({ ids: [menxia], timeout_ms: 600000 }) - - if (menxiaResult.timed_out) { - send_input({ id: menxia, message: "Please finalize review and output verdict (approved/rejected)." }) - const retry = wait({ ids: [menxia], timeout_ms: 120000 }) - } - - close_agent({ id: menxia }) - - // Parse verdict from review report - const reviewReport = Read(`${sessionDir}/review/menxia-review.md`) - approved = reviewReport.includes("approved") || reviewReport.includes("approved: true") - - if (!approved && reviewRound < 3) { - // Respawn zhongshu with rejection feedback (Stage 1 again) - // ... spawn zhongshu with rejection_feedback = reviewReport ... - } -} - -if (!approved && reviewRound >= 3) { - // Max rounds reached, ask user - AskUserQuestion("Menxia rejected the plan 3 times. Please review and decide: approve, reject, or provide guidance.") -} -``` - -#### Stage 3: Shangshu Dispatch - -```javascript -const shangshu = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~ or /.codex/skills/team-edict/agents/shangshu-dispatcher.md (MUST read first) -2. Read: ${sessionDir}/plan/zhongshu-plan.md (approved plan) -3. Read: ${sessionDir}/review/menxia-review.md (review conditions) -4. Read: ~ or /.codex/skills/team-edict/specs/team-config.json (routing rules) - ---- - -Goal: Parse approved plan and generate Six Ministries dispatch plan -Scope: Route subtasks to departments, define execution batches, set dependencies -Deliverables: ${sessionDir}/plan/dispatch-plan.md -` -}) - -const shangshuResult = wait({ ids: [shangshu], timeout_ms: 300000 }) -close_agent({ id: shangshu }) - -// Parse dispatch-plan.md to generate tasks.csv (Phase 1 input) -``` - -**Success Criteria**: -- zhongshu-plan.md written with structured subtask list -- menxia-review.md written with 4-dimensional analysis verdict -- dispatch-plan.md written with ministry assignments and batch ordering -- Interactive agents closed, results stored - ---- - -### Phase 1: Requirement -> CSV + Classification - -**Objective**: Parse the Shangshu dispatch plan into a tasks.csv with proper wave computation and exec_mode classification. - -**Decomposition Rules**: - -1. Read `${sessionDir}/plan/dispatch-plan.md` -2. For each ministry task in the dispatch plan: - - Extract: task ID, title, description, department, priority, batch number, acceptance criteria - - Determine dependencies from the dispatch plan's batch ordering and explicit blockedBy - - Set `context_from` for tasks that need predecessor findings -3. Apply classification rules (see Task Classification Rules above) -4. Compute waves via topological sort (Kahn's BFS with depth tracking) -5. Generate `tasks.csv` with all columns - -**Classification Rules**: - -| Department | Default exec_mode | Override Condition | -|------------|-------------------|-------------------| -| gongbu (IMPL) | csv-wave | Interactive if requires iterative codebase exploration | -| bingbu (OPS) | csv-wave | - | -| hubu (DATA) | csv-wave | - | -| libu (DOC) | csv-wave | - | -| libu-hr (HR) | csv-wave | - | -| xingbu (QA) | interactive | Always interactive (test-fix loop) | - -**Wave Computation**: Kahn's BFS topological sort with depth tracking (csv-wave tasks only). - -**User Validation**: Display task breakdown with wave + exec_mode assignment (skip if AUTO_YES). - -**Success Criteria**: -- tasks.csv created with valid schema, wave, and exec_mode assignments -- No circular dependencies -- User approved (or AUTO_YES) - ---- - -### Phase 2: Wave Execution Engine (Extended) - -**Objective**: Execute tasks wave-by-wave with hybrid mechanism support and cross-wave context propagation. - -``` -For each wave W in 1..max_wave: - - 1. FILTER csv-wave tasks where wave == W and status == "pending" - 2. CHECK dependencies: if any dep has status == "failed", mark task as "skipped" - 3. BUILD prev_context for each task from context_from references: - - For csv-wave predecessors: read findings from master tasks.csv - - For interactive predecessors: read from interactive/{id}-result.json - 4. GENERATE wave-{W}.csv with prev_context column added - 5. EXECUTE csv-wave tasks: - spawn_agents_on_csv({ - task_csv_path: "${sessionDir}/wave-{W}.csv", - instruction_path: "~ or /.codex/skills/team-edict/instructions/agent-instruction.md", - schema_path: "~ or /.codex/skills/team-edict/schemas/tasks-schema.md", - additional_instructions: "Session directory: ${sessionDir}. Department: {department}. Priority: {priority}.", - concurrency: CONCURRENCY - }) - 6. MERGE results back into master tasks.csv (update status, findings, artifact_path, error) - 7. EXECUTE interactive tasks for this wave (post-wave): - For each interactive task in wave W: - Read agents/qa-verifier.md - Spawn QA verifier agent with task context + wave results - Handle test-fix loop via send_input - Store result in interactive/{id}-result.json - Close agent, update registry.json - 8. CLEANUP: delete wave-{W}.csv - 9. LOG wave completion to context.md and discoveries.ndjson - - Wave completion check: - - All tasks completed or skipped -> proceed to next wave - - Any failed non-skippable task -> log error, continue (dependents will be skipped) -``` - -**Success Criteria**: -- All waves executed in order -- Both csv-wave and interactive tasks handled per wave -- Each wave's results merged into master CSV before next wave starts -- Dependent tasks skipped when predecessor failed -- discoveries.ndjson accumulated across all waves and mechanisms -- Interactive agent lifecycle tracked in registry.json - ---- - -### Phase 3: Post-Wave Interactive (Quality Aggregation) - -**Objective**: Collect all ministry outputs, validate against quality gates, and generate the final edict completion report. - -```javascript -const aggregator = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~ or /.codex/skills/team-edict/agents/aggregator.md (MUST read first) -2. Read: ${sessionDir}/tasks.csv (master state) -3. Read: ${sessionDir}/discoveries.ndjson (all discoveries) -4. Read: ~ or /.codex/skills/team-edict/specs/quality-gates.md (quality standards) - ---- - -Goal: Aggregate all ministry outputs into final edict completion report -Scope: All artifacts in ${sessionDir}/artifacts/, all interactive results -Deliverables: ${sessionDir}/context.md (final report) - -### Ministry Artifacts to Collect -${listAllArtifacts()} - -### Quality Gate Standards -Read from: ~ or /.codex/skills/team-edict/specs/quality-gates.md -` -}) - -const aggResult = wait({ ids: [aggregator], timeout_ms: 300000 }) -close_agent({ id: aggregator }) -``` - -**Success Criteria**: -- Post-wave interactive processing complete -- Interactive agents closed, results stored - ---- - -### Phase 4: Results Aggregation - -**Objective**: Generate final results and human-readable report. - -``` -1. READ master tasks.csv -2. EXPORT results.csv with final status for all tasks -3. GENERATE context.md (if not already done by aggregator): - - Edict summary - - Pipeline stages: Planning -> Review -> Dispatch -> Execution - - Per-department output summaries - - Quality gate results - - Discoveries summary -4. DISPLAY summary to user: - - Total tasks: N (completed: X, failed: Y, skipped: Z) - - Per-wave breakdown - - Key findings -5. CLEANUP: - - Close any remaining interactive agents (registry.json) - - Remove temporary wave CSV files -6. OFFER: view full report | retry failed tasks | done -``` - -**Success Criteria**: -- results.csv exported (all tasks, both modes) -- context.md generated -- All interactive agents closed (registry.json cleanup) -- Summary displayed to user - ---- - -## Shared Discovery Board Protocol - -All agents (both csv-wave and interactive) share a single `discoveries.ndjson` file for cross-agent knowledge propagation. - -### Discovery Types - -| Type | Dedup Key | Data Schema | Description | -|------|-----------|-------------|-------------| -| `codebase_pattern` | `pattern_name` | `{pattern_name, files, description}` | Identified codebase patterns and conventions | -| `dependency_found` | `dep_name` | `{dep_name, version, used_by}` | External dependency discoveries | -| `risk_identified` | `risk_id` | `{risk_id, severity, description, mitigation}` | Risk findings from any agent | -| `implementation_note` | `file_path` | `{file_path, note, line_range}` | Implementation decisions and notes | -| `test_result` | `test_suite` | `{test_suite, pass_rate, failures}` | Test execution results | -| `quality_issue` | `issue_id` | `{issue_id, severity, file, description}` | Quality issues found during review | -| `routing_note` | `task_id` | `{task_id, department, reason}` | Dispatch routing decisions | - -### Protocol - -```bash -# Append discovery (any agent, any mode) -echo '{"ts":"","worker":"{id}","type":"","data":{...}}' >> ${sessionDir}/discoveries.ndjson - -# Read discoveries (any agent, any mode) -# Read ${sessionDir}/discoveries.ndjson, parse each line as JSON -# Deduplicate by type + dedup_key -``` - -### Rules -- **Append-only**: Never modify or delete existing entries -- **Deduplicate on read**: When reading, use type + dedup_key to skip duplicates -- **Both mechanisms share**: csv-wave agents and interactive agents use the same file -- **Carry across waves**: Discoveries persist across all waves - ---- - -## Six Ministries Routing Rules - -Shangshu dispatcher uses these rules to assign tasks to ministries: - -| Keyword Signals | Target Ministry | Role ID | Task Prefix | -|----------------|-----------------|---------|-------------| -| Feature dev, architecture, code, refactor, implement, API | Engineering | gongbu | IMPL | -| Deploy, CI/CD, infrastructure, container, monitoring, security ops | Operations | bingbu | OPS | -| Data analysis, statistics, cost, reports, resource mgmt | Data & Resources | hubu | DATA | -| Documentation, README, UI copy, specs, API docs, comms | Documentation | libu | DOC | -| Testing, QA, bug, code review, compliance audit | Quality Assurance | xingbu | QA | -| Agent management, training, skill optimization, evaluation | Personnel | libu-hr | HR | - ---- - -## Kanban State Protocol - -All agents must report state transitions. In Codex context, agents write state to discoveries.ndjson: - -### State Machine - -``` -Pending -> Doing -> Done - | - Blocked (can enter at any time, must report reason) -``` - -### State Reporting via Discoveries - -```bash -# Task start -echo '{"ts":"","worker":"{id}","type":"state_update","data":{"state":"Doing","task_id":"{id}","department":"{department}","step":"Starting execution"}}' >> ${sessionDir}/discoveries.ndjson - -# Progress update -echo '{"ts":"","worker":"{id}","type":"progress","data":{"task_id":"{id}","current":"Step 2: Implementing API","plan":"Step1 done|Step2 in progress|Step3 pending"}}' >> ${sessionDir}/discoveries.ndjson - -# Completion -echo '{"ts":"","worker":"{id}","type":"state_update","data":{"state":"Done","task_id":"{id}","remark":"Completed: implementation summary"}}' >> ${sessionDir}/discoveries.ndjson - -# Blocked -echo '{"ts":"","worker":"{id}","type":"state_update","data":{"state":"Blocked","task_id":"{id}","reason":"Cannot proceed: missing dependency"}}' >> ${sessionDir}/discoveries.ndjson -``` - ---- - -## Interactive Task Execution - -For interactive tasks within a wave (primarily QA test-fix loops): - -**Spawn Protocol**: - -```javascript -const agent = spawn_agent({ - message: ` -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS (Agent Execute) -1. **Read role definition**: ~ or /.codex/skills/team-edict/agents/qa-verifier.md (MUST read first) -2. Read: ${sessionDir}/discoveries.ndjson (shared discoveries) -3. Read: ~ or /.codex/skills/team-edict/specs/quality-gates.md (quality standards) - ---- - -Goal: Execute QA verification for task ${taskId} -Scope: ${taskDescription} -Deliverables: Test report + pass/fail verdict - -### Previous Context -${prevContextFromCompletedTasks} - -### Acceptance Criteria -${acceptanceCriteria} -` -}) -``` - -**Wait + Process**: - -```javascript -const result = wait({ ids: [agent], timeout_ms: 600000 }) - -if (result.timed_out) { - send_input({ id: agent, message: "Please finalize and output current findings." }) - const retry = wait({ ids: [agent], timeout_ms: 120000 }) -} - -// Store result -Write(`${sessionDir}/interactive/${taskId}-result.json`, JSON.stringify({ - task_id: taskId, - status: "completed", - findings: parseFindings(result), - timestamp: new Date().toISOString() -})) -``` - -**Lifecycle Tracking**: - -```javascript -// On spawn: register -registry.active.push({ id: agent, task_id: taskId, pattern: "qa-verifier", spawned_at: now }) - -// On close: move to closed -close_agent({ id: agent }) -registry.active = registry.active.filter(a => a.id !== agent) -registry.closed.push({ id: agent, task_id: taskId, closed_at: now }) -``` - ---- - -## Cross-Mechanism Context Bridging - -### Interactive Result -> CSV Task - -When a pre-wave interactive task produces results needed by csv-wave tasks: - -```javascript -// 1. Interactive result stored in file -const resultFile = `${sessionDir}/interactive/${taskId}-result.json` - -// 2. Wave engine reads when building prev_context for csv-wave tasks -// If a csv-wave task has context_from referencing an interactive task: -// Read the interactive result file and include in prev_context -``` - -### CSV Result -> Interactive Task - -When a post-wave interactive task needs CSV wave results: - -```javascript -// Include in spawn message -const csvFindings = readMasterCSV().filter(t => t.wave === currentWave && t.exec_mode === 'csv-wave') -const context = csvFindings.map(t => `## Task ${t.id}: ${t.title}\n${t.findings}`).join('\n\n') - -spawn_agent({ - message: `...\n### Wave ${currentWave} Results\n${context}\n...` -}) -``` - ---- - -## Error Handling - -| Error | Resolution | -|-------|------------| -| Circular dependency | Detect in wave computation, abort with error message | -| CSV agent timeout | Mark as failed in results, continue with wave | -| CSV agent failed | Mark as failed, skip dependent tasks in later waves | -| Interactive agent timeout | Urge convergence via send_input, then close if still timed out | -| Interactive agent failed | Mark as failed, skip dependents | -| Pre-wave interactive failed | Skip dependent csv-wave tasks in same wave | -| All agents in wave failed | Log error, offer retry or abort | -| CSV parse error | Validate CSV format before execution, show line number | -| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries | -| Lifecycle leak | Cleanup all active agents via registry.json at end | -| Continue mode: no session found | List available sessions, prompt user to select | -| Menxia rejection loop >= 3 rounds | AskUserQuestion for user decision | -| Zhongshu plan file missing | Abort Phase 0, report error | -| Shangshu dispatch plan parse failure | Abort, ask user to review dispatch-plan.md | -| Ministry artifact not written | Mark task as failed, include in QA report | -| Test-fix loop exceeds 3 rounds | Mark QA as failed, report to aggregator | - ---- - -## Specs Reference - -| File | Content | Used By | -|------|---------|---------| -| [specs/team-config.json](specs/team-config.json) | Role registry, routing rules, pipeline definition, session structure, artifact paths | Orchestrator (session init), Shangshu (routing), all agents (artifact paths) | -| [specs/quality-gates.md](specs/quality-gates.md) | Per-phase quality gate standards, cross-phase consistency checks | Aggregator (Phase 3), QA verifier (test validation) | - ---- - -## Core Rules - -1. **Start Immediately**: First action is session initialization, then Phase 0 -2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged -3. **CSV is Source of Truth**: Master tasks.csv holds all state (both csv-wave and interactive) -4. **CSV First**: Default to csv-wave for tasks; only use interactive when interaction pattern requires it -5. **Context Propagation**: prev_context built from master CSV, not from memory -6. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson -- both mechanisms share it -7. **Skip on Failure**: If a dependency failed, skip the dependent task (regardless of mechanism) -8. **Lifecycle Balance**: Every spawn_agent MUST have a matching close_agent (tracked in registry.json) -9. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged -10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped -11. **Three Departments are Serial**: Zhongshu -> Menxia -> Shangshu must execute in strict order -12. **Rejection Loop Max 3**: Menxia can reject max 3 times before escalating to user -13. **Kanban is Mandatory**: All agents must report state transitions via discoveries.ndjson -14. **Quality Gates Apply**: Phase 3 aggregator validates all outputs against specs/quality-gates.md - ---- - -## Coordinator Role Constraints (Crown Prince / Main Agent) - -**CRITICAL**: The coordinator (main agent executing this skill) is responsible for **orchestration only**, NOT implementation. - -15. **Coordinator Does NOT Execute Code**: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned agents (Three Departments and Six Ministries). The coordinator only: - - Spawns agents with task assignments - - Waits for agent callbacks - - Merges results into master CSV - - Coordinates workflow transitions between phases - -16. **Patient Waiting is Mandatory**: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST: - - Wait patiently for `wait()` calls to complete - - NOT skip workflow steps due to perceived delays - - NOT assume agents have failed just because they're taking time - - Trust the timeout mechanisms (600s for planning, 300s for execution) - -17. **Use send_input for Clarification**: When agents need guidance or appear stuck, the coordinator MUST: - - Use `send_input()` to ask questions or provide clarification - - NOT skip the agent or move to next phase prematurely - - Give agents opportunity to respond before escalating - - Example: `send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })` - -18. **No Workflow Shortcuts**: The coordinator MUST NOT: - - Skip phases or stages (e.g., jumping from Zhongshu directly to Shangshu) - - Bypass the Three Departments serial pipeline - - Execute wave N before wave N-1 completes - - Assume task completion without explicit agent callback - - Make up or fabricate agent results - -19. **Respect Long-Running Processes**: This is a complex multi-agent workflow that requires patience: - - Total execution time: 30-90 minutes for typical edicts - - Phase 0 (Three Departments): 15-30 minutes - - Phase 2 (Wave Execution): 10-20 minutes per wave - - Phase 3 (Aggregation): 5-10 minutes - - The coordinator must remain active and attentive throughout the entire process - diff --git a/.codex/skills/team-edict/agents/aggregator.md b/.codex/skills/team-edict/agents/aggregator.md deleted file mode 100644 index b311b7b9..00000000 --- a/.codex/skills/team-edict/agents/aggregator.md +++ /dev/null @@ -1,246 +0,0 @@ -# Aggregator Agent - -Post-wave aggregation agent -- collects all ministry outputs, validates against quality gates, and generates the final edict completion report. - -## Identity - -- **Type**: `interactive` -- **Role**: aggregator (Final Report Generator) -- **Responsibility**: Collect all ministry artifacts, validate quality gates, generate final completion report - -## Boundaries - -### MUST - -- Load role definition via MANDATORY FIRST STEPS pattern -- Read ALL ministry artifacts from the session artifacts directory -- Read the master tasks.csv for completion status -- Read quality-gates.md and validate each phase -- Read all discoveries from discoveries.ndjson -- Generate a comprehensive final report (context.md) -- Include per-department output summaries -- Include quality gate validation results -- Highlight any failures, skipped tasks, or open issues - -### MUST NOT - -- Skip reading any existing artifact -- Ignore failed or skipped tasks in the report -- Modify any ministry artifacts -- Skip quality gate validation - ---- - -## Toolbox - -### Available Tools - -| Tool | Type | Purpose | -|------|------|---------| -| `Read` | file | Read artifacts, tasks.csv, specs, discoveries | -| `Write` | file | Write final context.md report | -| `Glob` | search | Find all artifact files | -| `Bash` | exec | Parse CSV, count stats | - ---- - -## Execution - -### Phase 1: Artifact Collection - -**Objective**: Gather all ministry outputs and task status - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| tasks.csv | Yes | Master state with all task statuses | -| artifacts/ directory | Yes | All ministry output files | -| interactive/ directory | No | Interactive task results (QA) | -| discoveries.ndjson | Yes | All shared discoveries | -| quality-gates.md | Yes | Quality standards | - -**Steps**: - -1. Read `/tasks.csv` and parse all task records -2. Use Glob to find all files in `/artifacts/` -3. Read each artifact file -4. Use Glob to find all files in `/interactive/` -5. Read each interactive result file -6. Read `/discoveries.ndjson` (all entries) -7. Read `~ or /.codex/skills/team-edict/specs/quality-gates.md` - -**Output**: All artifacts and status data collected - ---- - -### Phase 2: Quality Gate Validation - -**Objective**: Validate each phase against quality gate standards - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Collected artifacts | Yes | From Phase 1 | -| quality-gates.md | Yes | Quality standards | - -**Steps**: - -1. Validate Phase 0 (Three Departments): - - zhongshu-plan.md exists and has required sections - - menxia-review.md exists with clear verdict - - dispatch-plan.md exists with ministry assignments -2. Validate Phase 2 (Ministry Execution): - - Each department's artifact file exists - - Acceptance criteria verified (from tasks.csv findings) - - State reporting present in discoveries.ndjson -3. Validate QA results (if xingbu report exists): - - Test pass rate meets threshold (>= 95%) - - No unresolved Critical issues - - Code review completed -4. Score each quality gate: - | Score | Status | Action | - |-------|--------|--------| - | >= 80% | PASS | No action needed | - | 60-79% | WARNING | Log warning in report | - | < 60% | FAIL | Highlight in report | - -**Output**: Quality gate validation results - ---- - -### Phase 3: Report Generation - -**Objective**: Generate comprehensive final report - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Task data | Yes | From Phase 1 | -| Quality gate results | Yes | From Phase 2 | - -**Steps**: - -1. Compute summary statistics: - - Total tasks, completed, failed, skipped - - Per-wave breakdown - - Per-department breakdown -2. Extract key findings from discoveries.ndjson -3. Compile per-department summaries from artifacts -4. Generate context.md following template -5. Write to `/context.md` - -**Output**: context.md written - ---- - -## Final Report Template (context.md) - -```markdown -# Edict Completion Report - -## Edict Summary - - -## Pipeline Execution Summary -| Stage | Department | Status | Duration | -|-------|-----------|--------|----------| -| Planning | zhongshu | Completed | - | -| Review | menxia | Approved (Round N/3) | - | -| Dispatch | shangshu | Completed | - | -| Execution | Six Ministries | N/M completed | - | - -## Task Status Overview -- Total tasks: N -- Completed: X -- Failed: Y -- Skipped: Z - -### Per-Wave Breakdown -| Wave | Total | Completed | Failed | Skipped | -|------|-------|-----------|--------|---------| -| 1 | N | X | Y | Z | -| 2 | N | X | Y | Z | - -### Per-Department Breakdown -| Department | Tasks | Completed | Artifacts | -|------------|-------|-----------|-----------| -| gongbu | N | X | artifacts/gongbu-output.md | -| bingbu | N | X | artifacts/bingbu-output.md | -| hubu | N | X | artifacts/hubu-output.md | -| libu | N | X | artifacts/libu-output.md | -| libu-hr | N | X | artifacts/libu-hr-output.md | -| xingbu | N | X | artifacts/xingbu-report.md | - -## Department Output Summaries - -### gongbu (Engineering) - - -### bingbu (Operations) - - -### hubu (Data & Resources) - - -### libu (Documentation) - - -### libu-hr (Personnel) - - -### xingbu (Quality Assurance) - - -## Quality Gate Results -| Gate | Phase | Score | Status | -|------|-------|-------|--------| -| Planning quality | zhongshu | XX% | PASS/WARN/FAIL | -| Review thoroughness | menxia | XX% | PASS/WARN/FAIL | -| Dispatch completeness | shangshu | XX% | PASS/WARN/FAIL | -| Execution quality | ministries | XX% | PASS/WARN/FAIL | -| QA verification | xingbu | XX% | PASS/WARN/FAIL | - -## Key Discoveries - - -## Failures and Issues - - -## Open Items - -``` - ---- - -## Structured Output Template - -``` -## Summary -- Edict completion report generated: N/M tasks completed, quality gates: X PASS, Y WARN, Z FAIL - -## Findings -- Per-department completion rates -- Quality gate scores -- Key discoveries count - -## Deliverables -- File: /context.md - -## Open Questions -1. (any unresolved issues requiring user attention) -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Artifact file missing for a department | Note as "Not produced" in report, mark quality gate as FAIL | -| tasks.csv parse error | Attempt line-by-line parsing, skip malformed rows | -| discoveries.ndjson has malformed lines | Skip malformed lines, continue with valid entries | -| Quality gate data insufficient | Score as "Insufficient data", mark WARNING | -| No QA report (xingbu not assigned) | Skip QA quality gate, note in report | diff --git a/.codex/skills/team-edict/agents/menxia-reviewer.md b/.codex/skills/team-edict/agents/menxia-reviewer.md deleted file mode 100644 index aa04bad1..00000000 --- a/.codex/skills/team-edict/agents/menxia-reviewer.md +++ /dev/null @@ -1,229 +0,0 @@ -# Menxia Reviewer Agent - -Menxia (Chancellery / Review Department) -- performs multi-dimensional review of the Zhongshu plan from four perspectives: feasibility, completeness, risk, and resource allocation. Outputs approve/reject verdict. - -## Identity - -- **Type**: `interactive` -- **Role**: menxia (Chancellery / Multi-Dimensional Review) -- **Responsibility**: Four-dimensional parallel review, approve/reject verdict with detailed feedback - -## Boundaries - -### MUST - -- Load role definition via MANDATORY FIRST STEPS pattern -- Read the Zhongshu plan completely before starting review -- Analyze from ALL four dimensions (feasibility, completeness, risk, resource) -- Produce a clear verdict: approved or rejected -- If rejecting, provide specific, actionable feedback for each rejection point -- Write the review report to `/review/menxia-review.md` -- Report state transitions via discoveries.ndjson -- Apply weighted scoring: feasibility 30%, completeness 30%, risk 25%, resource 15% - -### MUST NOT - -- Approve a plan with unaddressed critical feasibility issues -- Reject without providing specific, actionable feedback -- Skip any of the four review dimensions -- Modify the Zhongshu plan (review only) -- Exceed the scope of review (no implementation suggestions beyond scope) - ---- - -## Toolbox - -### Available Tools - -| Tool | Type | Purpose | -|------|------|---------| -| `Read` | file | Read plan, specs, codebase files for verification | -| `Write` | file | Write review report to session directory | -| `Glob` | search | Find files to verify feasibility claims | -| `Grep` | search | Search codebase to validate technical assertions | -| `Bash` | exec | Run verification commands | - ---- - -## Execution - -### Phase 1: Plan Loading - -**Objective**: Load the Zhongshu plan and all review context - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| zhongshu-plan.md | Yes | Plan to review | -| Original edict | Yes | From spawn message | -| team-config.json | No | For routing rule validation | -| Previous review (if round > 1) | No | Previous rejection feedback | - -**Steps**: - -1. Read `/plan/zhongshu-plan.md` (the plan under review) -2. Parse edict text from spawn message for requirement cross-reference -3. Read `/discoveries.ndjson` for codebase pattern context -4. Report state "Doing": - ```bash - echo '{"ts":"","worker":"REVIEW-001","type":"state_update","data":{"state":"Doing","task_id":"REVIEW-001","department":"menxia","step":"Loading plan for review"}}' >> /discoveries.ndjson - ``` - -**Output**: Plan loaded, review context assembled - ---- - -### Phase 2: Four-Dimensional Analysis - -**Objective**: Evaluate the plan from four independent perspectives - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Loaded plan | Yes | From Phase 1 | -| Codebase | Yes | For feasibility verification | -| Original edict | Yes | For completeness check | - -**Steps**: - -#### Dimension 1: Feasibility Review (Weight: 30%) -1. Verify each technical path is achievable with current codebase -2. Check that required dependencies exist or can be added -3. Validate that proposed file structures make sense -4. Result: PASS / CONDITIONAL / FAIL - -#### Dimension 2: Completeness Review (Weight: 30%) -1. Cross-reference every requirement in the edict against subtask list -2. Identify any requirements not covered by subtasks -3. Check that acceptance criteria are measurable and cover all requirements -4. Result: COMPLETE / HAS GAPS - -#### Dimension 3: Risk Assessment (Weight: 25%) -1. Identify potential failure points in the plan -2. Check that each high-risk item has a mitigation strategy -3. Evaluate rollback feasibility -4. Result: ACCEPTABLE / HIGH RISK (unmitigated) - -#### Dimension 4: Resource Allocation (Weight: 15%) -1. Verify task-to-department mapping follows routing rules -2. Check workload balance across departments -3. Identify overloaded or idle departments -4. Result: BALANCED / NEEDS ADJUSTMENT - -For each dimension, record discoveries: -```bash -echo '{"ts":"","worker":"REVIEW-001","type":"quality_issue","data":{"issue_id":"MX-","severity":"","file":"plan/zhongshu-plan.md","description":""}}' >> /discoveries.ndjson -``` - -**Output**: Four-dimensional analysis results - ---- - -### Phase 3: Verdict Synthesis - -**Objective**: Combine dimension results into final verdict - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Dimension results | Yes | From Phase 2 | - -**Steps**: - -1. Apply scoring weights: - - Feasibility: 30% - - Completeness: 30% - - Risk: 25% - - Resource: 15% -2. Apply veto rules (immediate rejection): - - Feasibility = FAIL -> reject - - Completeness has critical gaps (core requirement uncovered) -> reject - - Risk has HIGH unmitigated items -> reject -3. Resource issues alone do not trigger rejection (conditional approval with notes) -4. Determine final verdict: approved or rejected -5. Write review report to `/review/menxia-review.md` - -**Output**: Review report with verdict - ---- - -## Review Report Template (menxia-review.md) - -```markdown -# Menxia Review Report - -## Review Verdict: [Approved / Rejected] -Round: N/3 - -## Four-Dimensional Analysis Summary -| Dimension | Weight | Result | Key Findings | -|-----------|--------|--------|-------------| -| Feasibility | 30% | PASS/CONDITIONAL/FAIL | | -| Completeness | 30% | COMPLETE/HAS GAPS | | -| Risk | 25% | ACCEPTABLE/HIGH RISK | | -| Resource | 15% | BALANCED/NEEDS ADJUSTMENT | | - -## Detailed Findings - -### Feasibility -- -- - -### Completeness -- -- - -### Risk -| Risk Item | Severity | Has Mitigation | Notes | -|-----------|----------|---------------|-------| -| | High/Med/Low | Yes/No | | - -### Resource Allocation -- -- - -## Rejection Feedback (if rejected) -1. : What must be changed and why -2. : What must be changed and why - -## Conditions (if conditionally approved) -- : What to watch during execution -- : Suggested adjustments -``` - ---- - -## Structured Output Template - -``` -## Summary -- Review completed: [Approved/Rejected] (Round N/3) - -## Findings -- Feasibility: [result] - [key finding] -- Completeness: [result] - [key finding] -- Risk: [result] - [key finding] -- Resource: [result] - [key finding] - -## Deliverables -- File: /review/menxia-review.md -- Verdict: approved=, round= - -## Open Questions -1. (if any ambiguities remain) -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Plan file not found | Report error, cannot proceed with review | -| Plan structure malformed | Note structural issues as feasibility finding, continue review | -| Cannot verify technical claims | Mark as "Unverified" in feasibility, do not auto-reject | -| Edict text not provided | Review plan on its own merits, note missing context | -| Timeout approaching | Output partial results with "PARTIAL" status on incomplete dimensions | diff --git a/.codex/skills/team-edict/agents/qa-verifier.md b/.codex/skills/team-edict/agents/qa-verifier.md deleted file mode 100644 index e51d3d66..00000000 --- a/.codex/skills/team-edict/agents/qa-verifier.md +++ /dev/null @@ -1,274 +0,0 @@ -# QA Verifier Agent - -Xingbu (Ministry of Justice / Quality Assurance) -- executes quality verification with iterative test-fix loops. Runs as interactive agent to support multi-round feedback cycles with implementation agents. - -## Identity - -- **Type**: `interactive` -- **Role**: xingbu (Ministry of Justice / QA Verifier) -- **Responsibility**: Code review, test execution, compliance audit, test-fix loop coordination - -## Boundaries - -### MUST - -- Load role definition via MANDATORY FIRST STEPS pattern -- Read quality-gates.md for quality standards -- Read the implementation artifacts before testing -- Execute comprehensive verification: code review + test execution + compliance -- Classify findings by severity: Critical / High / Medium / Low -- Support test-fix loop: report failures, wait for fixes, re-verify (max 3 rounds) -- Write QA report to `/artifacts/xingbu-report.md` -- Report state transitions via discoveries.ndjson -- Report test results as discoveries for cross-agent visibility - -### MUST NOT - -- Skip reading quality-gates.md -- Skip any verification dimension (review, test, compliance) -- Run more than 3 test-fix loop rounds -- Approve with unresolved Critical severity issues -- Modify implementation code (verification only, report issues for others to fix) - ---- - -## Toolbox - -### Available Tools - -| Tool | Type | Purpose | -|------|------|---------| -| `Read` | file | Read implementation artifacts, test files, quality standards | -| `Write` | file | Write QA report | -| `Glob` | search | Find test files, implementation files | -| `Grep` | search | Search for patterns, known issues, test markers | -| `Bash` | exec | Run test suites, linters, build commands | - ---- - -## Execution - -### Phase 1: Context Loading - -**Objective**: Load all verification context - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Task description | Yes | QA task details from spawn message | -| quality-gates.md | Yes | Quality standards | -| Implementation artifacts | Yes | Ministry outputs to verify | -| dispatch-plan.md | Yes | Acceptance criteria reference | -| discoveries.ndjson | No | Previous findings | - -**Steps**: - -1. Read `~ or /.codex/skills/team-edict/specs/quality-gates.md` -2. Read `/plan/dispatch-plan.md` for acceptance criteria -3. Read implementation artifacts from `/artifacts/` -4. Read `/discoveries.ndjson` for implementation notes -5. Report state "Doing": - ```bash - echo '{"ts":"","worker":"QA-001","type":"state_update","data":{"state":"Doing","task_id":"QA-001","department":"xingbu","step":"Loading context for QA verification"}}' >> /discoveries.ndjson - ``` - -**Output**: All verification context loaded - ---- - -### Phase 2: Code Review - -**Objective**: Review implementation code for quality issues - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Implementation files | Yes | Files modified/created by implementation tasks | -| Codebase conventions | Yes | From discoveries and existing code | - -**Steps**: - -1. Identify all files modified/created (from implementation artifacts and discoveries) -2. Read each file and review for: - - Code style consistency with existing codebase - - Error handling completeness - - Edge case coverage - - Security concerns (input validation, auth checks) - - Performance implications -3. Classify each finding by severity: - | Severity | Criteria | Blocks Approval | - |----------|----------|----------------| - | Critical | Security vulnerability, data loss risk, crash | Yes | - | High | Incorrect behavior, missing error handling | Yes | - | Medium | Code smell, minor inefficiency, style issue | No | - | Low | Suggestion, nitpick, documentation gap | No | -4. Record quality issues as discoveries: - ```bash - echo '{"ts":"","worker":"QA-001","type":"quality_issue","data":{"issue_id":"QI-","severity":"High","file":"src/auth/jwt.ts:23","description":"Missing input validation for refresh token"}}' >> /discoveries.ndjson - ``` - -**Output**: Code review findings with severity classifications - ---- - -### Phase 3: Test Execution - -**Objective**: Run tests and verify acceptance criteria - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Test files | If exist | Existing or generated test files | -| Acceptance criteria | Yes | From dispatch plan | - -**Steps**: - -1. Detect test framework: - ```bash - # Check for common test frameworks - ls package.json 2>/dev/null && cat package.json | grep -E '"jest"|"vitest"|"mocha"' - ls pytest.ini setup.cfg pyproject.toml 2>/dev/null - ``` -2. Run relevant test suites: - ```bash - # Example: npm test, pytest, etc. - npm test 2>&1 || true - ``` -3. Parse test results: - - Total tests, passed, failed, skipped - - Calculate pass rate -4. Verify acceptance criteria from dispatch plan: - - Check each criterion against actual results - - Mark as Pass/Fail with evidence -5. Record test results: - ```bash - echo '{"ts":"","worker":"QA-001","type":"test_result","data":{"test_suite":"","pass_rate":"%","failures":["",""]}}' >> /discoveries.ndjson - ``` - -**Output**: Test results with pass rate and acceptance criteria status - ---- - -### Phase 4: Test-Fix Loop (if failures found) - -**Objective**: Iterative fix cycle for test failures (max 3 rounds) - -This phase uses interactive send_input to report issues and receive fix confirmations. - -**Decision Table**: - -| Condition | Action | -|-----------|--------| -| Pass rate >= 95% AND no Critical issues | Exit loop, PASS | -| Pass rate < 95% AND round < 3 | Report failures, request fixes | -| Critical issues found AND round < 3 | Report Critical issues, request fixes | -| Round >= 3 AND still failing | Exit loop, FAIL with details | - -**Loop Protocol**: - -Round N (N = 1, 2, 3): -1. Report failures in structured format (findings written to discoveries.ndjson) -2. The orchestrator may send_input with fix confirmation -3. If fixes received: re-run tests (go to Phase 3) -4. If no fixes / timeout: proceed with current results - -**Output**: Final test results after fix loop - ---- - -### Phase 5: QA Report Generation - -**Objective**: Generate comprehensive QA report - -**Steps**: - -1. Compile all findings from Phases 2-4 -2. Write report to `/artifacts/xingbu-report.md` -3. Report completion state - ---- - -## QA Report Template (xingbu-report.md) - -```markdown -# Xingbu Quality Report - -## Overall Verdict: [PASS / FAIL] -- Test-fix rounds: N/3 - -## Code Review Summary -| Severity | Count | Blocking | -|----------|-------|----------| -| Critical | N | Yes | -| High | N | Yes | -| Medium | N | No | -| Low | N | No | - -### Critical/High Issues -- [C-001] file:line - description -- [H-001] file:line - description - -### Medium/Low Issues -- [M-001] file:line - description - -## Test Results -- Total tests: N -- Passed: N (XX%) -- Failed: N -- Skipped: N - -### Failed Tests -| Test | Failure Reason | Fix Status | -|------|---------------|------------| -| | | Fixed/Open | - -## Acceptance Criteria Verification -| Criterion | Status | Evidence | -|-----------|--------|----------| -| | Pass/Fail | | - -## Compliance Status -- Security: [Clean / Issues Found] -- Error Handling: [Complete / Gaps] -- Code Style: [Consistent / Inconsistent] - -## Recommendations -- -- -``` - ---- - -## Structured Output Template - -``` -## Summary -- QA verification [PASSED/FAILED] (test-fix rounds: N/3) - -## Findings -- Code review: N Critical, N High, N Medium, N Low issues -- Tests: XX% pass rate (N/M passed) -- Acceptance criteria: N/M met - -## Deliverables -- File: /artifacts/xingbu-report.md - -## Open Questions -1. (if any verification gaps) -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| No test framework detected | Run manual verification, note in report | -| Test suite crashes (not failures) | Report as Critical issue, attempt partial run | -| Implementation artifacts missing | Report as FAIL, cannot verify | -| Fix timeout in test-fix loop | Continue with current results, note unfixed items | -| Acceptance criteria ambiguous | Interpret conservatively, note assumptions | -| Timeout approaching | Output partial results with "PARTIAL" status | diff --git a/.codex/skills/team-edict/agents/shangshu-dispatcher.md b/.codex/skills/team-edict/agents/shangshu-dispatcher.md deleted file mode 100644 index 36970e8a..00000000 --- a/.codex/skills/team-edict/agents/shangshu-dispatcher.md +++ /dev/null @@ -1,247 +0,0 @@ -# Shangshu Dispatcher Agent - -Shangshu (Department of State Affairs / Dispatch) -- parses the approved plan, routes subtasks to the Six Ministries based on routing rules, and generates a structured dispatch plan with dependency batches. - -## Identity - -- **Type**: `interactive` -- **Role**: shangshu (Department of State Affairs / Dispatch) -- **Responsibility**: Parse approved plan, route tasks to ministries, generate dispatch plan with dependency ordering - -## Boundaries - -### MUST - -- Load role definition via MANDATORY FIRST STEPS pattern -- Read both the Zhongshu plan and Menxia review (for conditions) -- Apply routing rules from team-config.json strictly -- Split cross-department tasks into separate ministry-level tasks -- Define clear dependency ordering between batches -- Write dispatch plan to `/plan/dispatch-plan.md` -- Ensure every subtask has: department assignment, task ID (DEPT-NNN), dependencies, acceptance criteria -- Report state transitions via discoveries.ndjson - -### MUST NOT - -- Route tasks to wrong departments (must follow keyword-signal rules) -- Leave any subtask unassigned to a department -- Create circular dependencies between batches -- Modify the plan content (dispatch only) -- Ignore conditions from Menxia review - ---- - -## Toolbox - -### Available Tools - -| Tool | Type | Purpose | -|------|------|---------| -| `Read` | file | Read plan, review, team-config | -| `Write` | file | Write dispatch plan to session directory | -| `Glob` | search | Verify file references in plan | -| `Grep` | search | Search for keywords for routing decisions | - ---- - -## Execution - -### Phase 1: Context Loading - -**Objective**: Load approved plan, review conditions, and routing rules - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| zhongshu-plan.md | Yes | Approved execution plan | -| menxia-review.md | Yes | Review conditions to carry forward | -| team-config.json | Yes | Routing rules for department assignment | - -**Steps**: - -1. Read `/plan/zhongshu-plan.md` -2. Read `/review/menxia-review.md` -3. Read `~ or /.codex/skills/team-edict/specs/team-config.json` -4. Extract subtask list from plan -5. Extract conditions from review -6. Report state "Doing": - ```bash - echo '{"ts":"","worker":"DISPATCH-001","type":"state_update","data":{"state":"Doing","task_id":"DISPATCH-001","department":"shangshu","step":"Loading approved plan for dispatch"}}' >> /discoveries.ndjson - ``` - -**Output**: Plan parsed, routing rules loaded - ---- - -### Phase 2: Routing Analysis - -**Objective**: Assign each subtask to the correct ministry - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Subtask list | Yes | From Phase 1 | -| Routing rules | Yes | From team-config.json | - -**Steps**: - -1. For each subtask, extract keywords and match against routing rules: - | Keyword Signals | Target Ministry | Task Prefix | - |----------------|-----------------|-------------| - | Feature, architecture, code, refactor, implement, API | gongbu | IMPL | - | Deploy, CI/CD, infrastructure, container, monitoring, security ops | bingbu | OPS | - | Data analysis, statistics, cost, reports, resource mgmt | hubu | DATA | - | Documentation, README, UI copy, specs, API docs | libu | DOC | - | Testing, QA, bug, code review, compliance | xingbu | QA | - | Agent management, training, skill optimization | libu-hr | HR | - -2. If a subtask spans multiple departments (e.g., "implement + test"), split into separate tasks -3. Assign task IDs: DEPT-NNN (e.g., IMPL-001, QA-001) -4. Record routing decisions as discoveries: - ```bash - echo '{"ts":"","worker":"DISPATCH-001","type":"routing_note","data":{"task_id":"IMPL-001","department":"gongbu","reason":"Keywords: implement, API endpoint"}}' >> /discoveries.ndjson - ``` - -**Output**: All subtasks assigned to departments with task IDs - ---- - -### Phase 3: Dependency Analysis and Batch Ordering - -**Objective**: Organize tasks into execution batches based on dependencies - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Routed task list | Yes | From Phase 2 | - -**Steps**: - -1. Analyze dependencies between tasks: - - Implementation before testing (IMPL before QA) - - Implementation before documentation (IMPL before DOC) - - Infrastructure can parallel with implementation (OPS parallel with IMPL) - - Data tasks may depend on implementation (DATA after IMPL if needed) -2. Group into batches: - - Batch 1: No-dependency tasks (parallel) - - Batch 2: Tasks depending on Batch 1 (parallel within batch) - - Batch N: Tasks depending on Batch N-1 -3. Validate no circular dependencies -4. Determine exec_mode for each task: - - xingbu (QA) tasks with test-fix loops -> `interactive` - - All others -> `csv-wave` - -**Output**: Batched task list with dependencies - ---- - -### Phase 4: Dispatch Plan Generation - -**Objective**: Write the structured dispatch plan - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Batched task list | Yes | From Phase 3 | -| Menxia conditions | No | From Phase 1 | - -**Steps**: - -1. Generate dispatch-plan.md following template below -2. Write to `/plan/dispatch-plan.md` -3. Report completion state - -**Output**: dispatch-plan.md written - ---- - -## Dispatch Plan Template (dispatch-plan.md) - -```markdown -# Shangshu Dispatch Plan - -## Dispatch Overview -- Total subtasks: N -- Departments involved: -- Execution batches: M batches - -## Task Assignments - -### Batch 1 (No dependencies, parallel execution) - -#### IMPL-001: -- **Department**: gongbu (Engineering) -- **Description**: -- **Priority**: P0 -- **Dependencies**: None -- **Acceptance Criteria**: -- **exec_mode**: csv-wave - -#### OPS-001: -- **Department**: bingbu (Operations) -- **Description**: -- **Priority**: P0 -- **Dependencies**: None -- **Acceptance Criteria**: -- **exec_mode**: csv-wave - -### Batch 2 (Depends on Batch 1) - -#### DOC-001: -- **Department**: libu (Documentation) -- **Description**: -- **Priority**: P1 -- **Dependencies**: IMPL-001 -- **Acceptance Criteria**: -- **exec_mode**: csv-wave - -#### QA-001: -- **Department**: xingbu (Quality Assurance) -- **Description**: -- **Priority**: P1 -- **Dependencies**: IMPL-001 -- **Acceptance Criteria**: -- **exec_mode**: interactive (test-fix loop) - -## Overall Acceptance Criteria - - -## Menxia Review Conditions (carry forward) - -``` - ---- - -## Structured Output Template - -``` -## Summary -- Dispatch plan generated: N tasks across M departments in B batches - -## Findings -- Routing: N tasks assigned (IMPL: X, OPS: Y, DOC: Z, QA: W, ...) -- Dependencies: B execution batches identified -- Interactive tasks: N (QA test-fix loops) - -## Deliverables -- File: /plan/dispatch-plan.md - -## Open Questions -1. (if any routing ambiguities) -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Subtask doesn't match any routing rule | Assign to gongbu by default, note in routing_note discovery | -| Plan has no clear subtasks | Extract implicit tasks from strategy section, note assumptions | -| Circular dependency detected | Break cycle by removing lowest-priority dependency, note in plan | -| Menxia conditions conflict with plan | Prioritize Menxia conditions, note conflict in dispatch plan | -| Single-task plan | Create minimal batch (1 task), add QA task if not present | diff --git a/.codex/skills/team-edict/agents/zhongshu-planner.md b/.codex/skills/team-edict/agents/zhongshu-planner.md deleted file mode 100644 index be268a53..00000000 --- a/.codex/skills/team-edict/agents/zhongshu-planner.md +++ /dev/null @@ -1,198 +0,0 @@ -# Zhongshu Planner Agent - -Zhongshu (Central Secretariat) -- analyzes the edict, explores the codebase, and drafts a structured execution plan with ministry-level subtask decomposition. - -## Identity - -- **Type**: `interactive` -- **Role**: zhongshu (Central Secretariat / Planning Department) -- **Responsibility**: Analyze edict requirements, explore codebase for feasibility, draft structured execution plan - -## Boundaries - -### MUST - -- Load role definition via MANDATORY FIRST STEPS pattern -- Produce structured output following the plan template -- Explore the codebase to ground the plan in reality -- Decompose the edict into concrete, ministry-assignable subtasks -- Define measurable acceptance criteria for each subtask -- Identify risks and propose mitigation strategies -- Write the plan to the session's `plan/zhongshu-plan.md` -- Report state transitions via discoveries.ndjson (Doing -> Done) -- If this is a rejection revision round, address ALL feedback from menxia-review.md - -### MUST NOT - -- Skip codebase exploration (unless explicitly told to skip) -- Create subtasks that span multiple departments (split them instead) -- Leave acceptance criteria vague or unmeasurable -- Implement any code (planning only) -- Ignore rejection feedback from previous Menxia review rounds - ---- - -## Toolbox - -### Available Tools - -| Tool | Type | Purpose | -|------|------|---------| -| `Read` | file | Read codebase files, specs, previous plans/reviews | -| `Write` | file | Write execution plan to session directory | -| `Glob` | search | Find files by pattern for codebase exploration | -| `Grep` | search | Search for patterns, keywords, implementations | -| `Bash` | exec | Run shell commands for exploration | - ---- - -## Execution - -### Phase 1: Context Loading - -**Objective**: Understand the edict and load all relevant context - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Edict text | Yes | Original task requirement from spawn message | -| team-config.json | Yes | Routing rules, department definitions | -| Previous menxia-review.md | If revision | Rejection feedback to address | -| Session discoveries.ndjson | No | Shared findings from previous stages | - -**Steps**: - -1. Parse the edict text from the spawn message -2. Read `~ or /.codex/skills/team-edict/specs/team-config.json` for routing rules -3. If revision round: Read `/review/menxia-review.md` for rejection feedback -4. Read `/discoveries.ndjson` if it exists - -**Output**: Parsed requirements + routing rules loaded - ---- - -### Phase 2: Codebase Exploration - -**Objective**: Ground the plan in the actual codebase - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Edict requirements | Yes | Parsed from Phase 1 | -| Codebase | Yes | Project files for exploration | - -**Steps**: - -1. Use Glob/Grep to identify relevant modules and files -2. Read key files to understand existing architecture -3. Identify patterns, conventions, and reusable components -4. Map dependencies and integration points -5. Record codebase patterns as discoveries: - ```bash - echo '{"ts":"","worker":"PLAN-001","type":"codebase_pattern","data":{"pattern_name":"","files":["",""],"description":""}}' >> /discoveries.ndjson - ``` - -**Output**: Codebase understanding sufficient for planning - ---- - -### Phase 3: Plan Drafting - -**Objective**: Create a structured execution plan with ministry assignments - -**Input**: - -| Source | Required | Description | -|--------|----------|-------------| -| Codebase analysis | Yes | From Phase 2 | -| Routing rules | Yes | From team-config.json | -| Rejection feedback | If revision | From menxia-review.md | - -**Steps**: - -1. Determine high-level execution strategy -2. Decompose into ministry-level subtasks using routing rules: - - Feature/code tasks -> gongbu (IMPL) - - Infrastructure/deploy tasks -> bingbu (OPS) - - Data/analytics tasks -> hubu (DATA) - - Documentation tasks -> libu (DOC) - - Agent/training tasks -> libu-hr (HR) - - Testing/QA tasks -> xingbu (QA) -3. For each subtask: define title, description, priority, dependencies, acceptance criteria -4. If revision round: address each rejection point with specific changes -5. Identify risks and define mitigation/rollback strategies -6. Write plan to `/plan/zhongshu-plan.md` - -**Output**: Structured plan file written - ---- - -## Plan Template (zhongshu-plan.md) - -```markdown -# Execution Plan - -## Revision History (if applicable) -- Round N: Addressed menxia feedback on [items] - -## Edict Description - - -## Technical Analysis - -- Relevant modules: ... -- Existing patterns: ... -- Dependencies: ... - -## Execution Strategy - - -## Subtask List -| Department | Task ID | Subtask | Priority | Dependencies | Expected Output | -|------------|---------|---------|----------|-------------|-----------------| -| gongbu | IMPL-001 | | P0 | None | | -| xingbu | QA-001 | | P1 | IMPL-001 | Test report | -... - -## Acceptance Criteria -- Criterion 1: -- Criterion 2: - -## Risk Assessment -| Risk | Probability | Impact | Mitigation | -|------|------------|--------|------------| -| | High/Med/Low | High/Med/Low | | -``` - ---- - -## Structured Output Template - -``` -## Summary -- Plan drafted with N subtasks across M departments - -## Findings -- Codebase exploration: identified key patterns in [modules] -- Risk assessment: N risks identified, all with mitigation plans - -## Deliverables -- File: /plan/zhongshu-plan.md - -## Open Questions -1. Any ambiguities in the edict (if any) -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Edict text too vague | List assumptions in plan, continue with best interpretation | -| Codebase exploration timeout | Draft plan based on edict alone, mark "Technical analysis: pending verification" | -| No clear department mapping | Assign to gongbu (engineering) by default, note in plan | -| Revision feedback contradictory | Address each point, note contradictions in "Open Questions" | -| Input file not found | Report in Open Questions, continue with available data | diff --git a/.codex/skills/team-edict/instructions/agent-instruction.md b/.codex/skills/team-edict/instructions/agent-instruction.md deleted file mode 100644 index b80c9ef0..00000000 --- a/.codex/skills/team-edict/instructions/agent-instruction.md +++ /dev/null @@ -1,177 +0,0 @@ -## TASK ASSIGNMENT - -### MANDATORY FIRST STEPS -1. Read shared discoveries: .workflow/.csv-wave/{session-id}/discoveries.ndjson (if exists, skip if not) -2. Read dispatch plan: .workflow/.csv-wave/{session-id}/plan/dispatch-plan.md (task details and acceptance criteria) -3. Read approved plan: .workflow/.csv-wave/{session-id}/plan/zhongshu-plan.md (overall strategy and context) -4. Read quality gates: ~ or /.codex/skills/team-edict/specs/quality-gates.md (quality standards) -5. Read team config: ~ or /.codex/skills/team-edict/specs/team-config.json (routing rules and artifact paths) - -> **Note**: The session directory path is provided by the orchestrator in `additional_instructions`. Use it to resolve the paths above. - ---- - -## Your Task - -**Task ID**: {id} -**Title**: {title} -**Description**: {description} -**Department**: {department} -**Task Prefix**: {task_prefix} -**Priority**: {priority} -**Dispatch Batch**: {dispatch_batch} -**Acceptance Criteria**: {acceptance_criteria} - -### Previous Tasks' Findings (Context) -{prev_context} - ---- - -## Execution Protocol - -1. **Read discoveries**: Load the session's discoveries.ndjson for shared exploration findings from other agents -2. **Use context**: Apply previous tasks' findings from prev_context above -3. **Report state start**: Append a state_update discovery with state "Doing": - ```bash - echo '{{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","worker":"{id}","type":"state_update","data":{{"state":"Doing","task_id":"{id}","department":"{department}","step":"Starting: {title}"}}}}' >> .workflow/.csv-wave/{session-id}/discoveries.ndjson - ``` -4. **Execute based on department**: - - **If department = gongbu (Engineering)**: - - Read target files listed in description - - Explore codebase to understand existing patterns and conventions - - Implement changes following project coding style - - Validate changes compile/lint correctly (use IDE diagnostics if available) - - Write output artifact to session artifacts directory - - Run relevant tests if available - - **If department = bingbu (Operations)**: - - Analyze infrastructure requirements from description - - Create/modify deployment scripts, CI/CD configs, or monitoring setup - - Validate configuration syntax - - Write output artifact to session artifacts directory - - **If department = hubu (Data & Resources)**: - - Analyze data sources and requirements from description - - Perform data analysis, generate reports or dashboards - - Include key metrics and visualizations where applicable - - Write output artifact to session artifacts directory - - **If department = libu (Documentation)**: - - Read source code and existing documentation - - Generate documentation following format specified in description - - Ensure accuracy against current implementation - - Include code examples where appropriate - - Write output artifact to session artifacts directory - - **If department = libu-hr (Personnel)**: - - Read agent/skill files as needed - - Analyze patterns, generate training materials or evaluations - - Write output artifact to session artifacts directory - - **If department = xingbu (Quality Assurance)**: - - This department typically runs as interactive (test-fix loop) - - If running as csv-wave: execute one-shot review/audit - - Read code and test files, run analysis - - Classify findings by severity (Critical/High/Medium/Low) - - Write report artifact to session artifacts directory - -5. **Write artifact**: Save your output to the appropriate artifact file: - - gongbu -> `artifacts/gongbu-output.md` - - bingbu -> `artifacts/bingbu-output.md` - - hubu -> `artifacts/hubu-output.md` - - libu -> `artifacts/libu-output.md` - - libu-hr -> `artifacts/libu-hr-output.md` - - xingbu -> `artifacts/xingbu-report.md` - - If multiple tasks exist for the same department, append task ID: `artifacts/gongbu-output-{id}.md` - -6. **Share discoveries**: Append exploration findings to shared board: - ```bash - echo '{{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","worker":"{id}","type":"","data":{{...}}}}' >> .workflow/.csv-wave/{session-id}/discoveries.ndjson - ``` - -7. **Report completion state**: - ```bash - echo '{{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","worker":"{id}","type":"state_update","data":{{"state":"Done","task_id":"{id}","department":"{department}","remark":"Completed: "}}}}' >> .workflow/.csv-wave/{session-id}/discoveries.ndjson - ``` - -8. **Report result**: Return JSON via report_agent_job_result - -### Discovery Types to Share -- `codebase_pattern`: `{pattern_name, files, description}` -- Identified codebase patterns and conventions -- `dependency_found`: `{dep_name, version, used_by}` -- External dependency discoveries -- `risk_identified`: `{risk_id, severity, description, mitigation}` -- Risk findings -- `implementation_note`: `{file_path, note, line_range}` -- Implementation decisions -- `test_result`: `{test_suite, pass_rate, failures}` -- Test execution results -- `quality_issue`: `{issue_id, severity, file, description}` -- Quality issues found - ---- - -## Artifact Output Format - -Write your artifact file in this structure: - -```markdown -# {department} Output Report -- {id} - -## Task -{title} - -## Implementation Summary - - -## Files Modified/Created -- `path/to/file1` -- description of change -- `path/to/file2` -- description of change - -## Acceptance Criteria Verification -| Criterion | Status | Evidence | -|-----------|--------|----------| -| | Pass/Fail | | - -## Key Findings -- Finding 1 with file:line reference -- Finding 2 with file:line reference - -## Risks / Open Issues -- Any remaining risks or issues (if none, state "None identified") -``` - ---- - -## Output (report_agent_job_result) - -Return JSON: -```json -{ - "id": "{id}", - "status": "completed", - "findings": "Key discoveries and implementation notes (max 500 chars)", - "artifact_path": "artifacts/-output.md", - "error": "" -} -``` - -If the task fails: -```json -{ - "id": "{id}", - "status": "failed", - "findings": "Partial progress description", - "artifact_path": "", - "error": "Specific error description" -} -``` - ---- - -## Error Handling - -| Scenario | Resolution | -|----------|------------| -| Target files not found | Report in findings, attempt with available context | -| Acceptance criteria ambiguous | Interpret conservatively, note assumption in findings | -| Blocked by missing dependency output | Report "Blocked" state in discoveries, set status to failed with reason | -| Compilation/lint errors in changes | Attempt to fix; if unfixable, report in findings with details | -| Test failures | Report in findings with specific failures, continue with remaining work | diff --git a/.codex/skills/team-edict/schemas/tasks-schema.md b/.codex/skills/team-edict/schemas/tasks-schema.md deleted file mode 100644 index 1f9f3380..00000000 --- a/.codex/skills/team-edict/schemas/tasks-schema.md +++ /dev/null @@ -1,163 +0,0 @@ -# Team Edict -- CSV Schema - -## Master CSV: tasks.csv - -### Column Definitions - -#### Input Columns (Set by Decomposer) - -| Column | Type | Required | Description | Example | -|--------|------|----------|-------------|---------| -| `id` | string | Yes | Unique task identifier (DEPT-NNN format) | `"IMPL-001"` | -| `title` | string | Yes | Short task title | `"Implement JWT auth middleware"` | -| `description` | string | Yes | Detailed task description (self-contained for agent) | `"Create JWT authentication middleware..."` | -| `deps` | string | No | Semicolon-separated dependency task IDs | `"IMPL-001;IMPL-002"` | -| `context_from` | string | No | Semicolon-separated task IDs for context | `"IMPL-001"` | -| `exec_mode` | enum | Yes | Execution mechanism: `csv-wave` or `interactive` | `"csv-wave"` | -| `department` | string | Yes | Target ministry: gongbu/bingbu/hubu/libu/libu-hr/xingbu | `"gongbu"` | -| `task_prefix` | string | Yes | Task type prefix: IMPL/OPS/DATA/DOC/HR/QA | `"IMPL"` | -| `priority` | string | Yes | Priority level: P0 (highest) to P3 (lowest) | `"P0"` | -| `dispatch_batch` | integer | Yes | Batch number from Shangshu dispatch plan (1-based) | `1` | -| `acceptance_criteria` | string | Yes | Specific measurable acceptance criteria | `"All auth endpoints return valid JWT"` | - -#### Computed Columns (Set by Wave Engine) - -| Column | Type | Description | Example | -|--------|------|-------------|---------| -| `wave` | integer | Wave number (1-based, from topological sort) | `2` | -| `prev_context` | string | Aggregated findings from context_from tasks (per-wave CSV only) | `"[IMPL-001] Created auth middleware..."` | - -#### Output Columns (Set by Agent) - -| Column | Type | Description | Example | -|--------|------|-------------|---------| -| `status` | enum | `pending` -> `completed` / `failed` / `skipped` | `"completed"` | -| `findings` | string | Key discoveries (max 500 chars) | `"Created 3 files, JWT validation working"` | -| `artifact_path` | string | Path to output artifact relative to session dir | `"artifacts/gongbu-output.md"` | -| `error` | string | Error message if failed | `""` | - ---- - -### exec_mode Values - -| Value | Mechanism | Description | -|-------|-----------|-------------| -| `csv-wave` | `spawn_agents_on_csv` | One-shot batch execution within wave | -| `interactive` | `spawn_agent`/`wait`/`send_input`/`close_agent` | Multi-round individual execution | - -Interactive tasks appear in master CSV for dependency tracking but are NOT included in wave-{N}.csv files. - ---- - -### Example Data - -```csv -id,title,description,deps,context_from,exec_mode,department,task_prefix,priority,dispatch_batch,acceptance_criteria,wave,status,findings,artifact_path,error -IMPL-001,"Implement JWT auth","Create JWT authentication middleware with token generation, validation, and refresh. Use existing bcrypt patterns from src/auth/. Follow Express middleware convention.","","","csv-wave","gongbu","IMPL","P0","1","JWT tokens generated and validated correctly; middleware integrates with existing auth flow","1","pending","","","" -OPS-001,"Configure CI pipeline","Set up GitHub Actions CI pipeline with test, lint, and build stages for the auth module.","","","csv-wave","bingbu","OPS","P0","1","CI pipeline runs on PR and push to main; all stages pass","1","pending","","","" -DOC-001,"Write auth API docs","Generate OpenAPI 3.0 documentation for all authentication endpoints including JWT token flows.","IMPL-001","IMPL-001","csv-wave","libu","DOC","P1","2","API docs cover all auth endpoints with request/response examples","2","pending","","","" -DATA-001,"Auth metrics dashboard","Create dashboard showing auth success/failure rates, token expiry distribution, and active sessions.","IMPL-001","IMPL-001","csv-wave","hubu","DATA","P2","2","Dashboard displays real-time auth metrics with 4 key charts","2","pending","","","" -QA-001,"Test auth module","Execute comprehensive test suite for auth module. Run unit tests, integration tests, and security scans. Test-fix loop with gongbu if failures found.","IMPL-001","IMPL-001","interactive","xingbu","QA","P1","2","Test pass rate >= 95%; no Critical security issues; code review clean","2","pending","","","" -``` - ---- - -### Column Lifecycle - -``` -Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution) ---------------------- -------------------- ----------------- -id ----------> id ----------> id -title ----------> title ----------> (reads) -description ----------> description ----------> (reads) -deps ----------> deps ----------> (reads) -context_from----------> context_from----------> (reads) -exec_mode ----------> exec_mode ----------> (reads) -department ----------> department ----------> (reads) -task_prefix ----------> task_prefix ----------> (reads) -priority ----------> priority ----------> (reads) -dispatch_batch--------> dispatch_batch--------> (reads) -acceptance_criteria---> acceptance_criteria---> (reads) - wave ----------> (reads) - prev_context ----------> (reads) - status - findings - artifact_path - error -``` - ---- - -## Output Schema (JSON) - -Agent output via `report_agent_job_result` (csv-wave tasks): - -```json -{ - "id": "IMPL-001", - "status": "completed", - "findings": "Implemented JWT auth middleware in src/auth/jwt.ts. Created token generation, validation, and refresh endpoints. Integrated with existing bcrypt password flow.", - "artifact_path": "artifacts/gongbu-output.md", - "error": "" -} -``` - -Interactive tasks output via structured text or JSON written to `interactive/{id}-result.json`. - ---- - -## Discovery Types - -| Type | Dedup Key | Data Schema | Description | -|------|-----------|-------------|-------------| -| `codebase_pattern` | `pattern_name` | `{pattern_name, files, description}` | Identified codebase patterns and conventions | -| `dependency_found` | `dep_name` | `{dep_name, version, used_by}` | External dependency discoveries | -| `risk_identified` | `risk_id` | `{risk_id, severity, description, mitigation}` | Risk findings from any agent | -| `implementation_note` | `file_path` | `{file_path, note, line_range}` | Implementation decisions and notes | -| `test_result` | `test_suite` | `{test_suite, pass_rate, failures}` | Test execution results | -| `quality_issue` | `issue_id` | `{issue_id, severity, file, description}` | Quality issues found during review | -| `routing_note` | `task_id` | `{task_id, department, reason}` | Dispatch routing decisions | -| `state_update` | `task_id` | `{state, task_id, department, step}` | Kanban state transition | -| `progress` | `task_id` | `{task_id, current, plan}` | Progress update within task | - -### Discovery NDJSON Format - -```jsonl -{"ts":"2026-03-08T14:30:00Z","worker":"IMPL-001","type":"state_update","data":{"state":"Doing","task_id":"IMPL-001","department":"gongbu","step":"Starting JWT implementation"}} -{"ts":"2026-03-08T14:35:00Z","worker":"IMPL-001","type":"codebase_pattern","data":{"pattern_name":"express-middleware","files":["src/middleware/auth.ts","src/middleware/cors.ts"],"description":"Express middleware follows handler(req,res,next) pattern with error wrapper"}} -{"ts":"2026-03-08T14:40:00Z","worker":"IMPL-001","type":"implementation_note","data":{"file_path":"src/auth/jwt.ts","note":"Using jsonwebtoken library, RS256 algorithm for token signing","line_range":"1-45"}} -{"ts":"2026-03-08T14:50:00Z","worker":"QA-001","type":"test_result","data":{"test_suite":"auth-unit","pass_rate":"97%","failures":["token-expiry-edge-case"]}} -{"ts":"2026-03-08T14:55:00Z","worker":"QA-001","type":"quality_issue","data":{"issue_id":"QI-001","severity":"Medium","file":"src/auth/jwt.ts:23","description":"Missing input validation for refresh token format"}} -``` - -> Both csv-wave and interactive agents read/write the same discoveries.ndjson file. - ---- - -## Cross-Mechanism Context Flow - -| Source | Target | Mechanism | -|--------|--------|-----------| -| CSV task findings | Interactive task | Injected via spawn message or send_input | -| Interactive task result | CSV task prev_context | Read from interactive/{id}-result.json | -| Any agent discovery | Any agent | Shared via discoveries.ndjson | -| Phase 0 plan/review | CSV tasks | Plan and review files in session dir | - ---- - -## Validation Rules - -| Rule | Check | Error | -|------|-------|-------| -| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" | -| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" | -| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" | -| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" | -| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" | -| exec_mode valid | Value is `csv-wave` or `interactive` | "Invalid exec_mode: {value}" | -| Description non-empty | Every task has description | "Empty description for task: {id}" | -| Status enum | status in {pending, completed, failed, skipped} | "Invalid status: {status}" | -| Cross-mechanism deps | Interactive->CSV deps resolve correctly | "Cross-mechanism dependency unresolvable: {id}" | -| Department valid | Value in {gongbu, bingbu, hubu, libu, libu-hr, xingbu} | "Invalid department: {value}" | -| Task prefix matches dept | IMPL->gongbu, OPS->bingbu, DATA->hubu, DOC->libu, HR->libu-hr, QA->xingbu | "Prefix-department mismatch: {id}" | -| Acceptance criteria non-empty | Every task has acceptance_criteria | "Empty acceptance criteria for task: {id}" | diff --git a/codex-lens-v2/README.md b/codex-lens-v2/README.md index 1a3cf2b3..23c52d16 100644 --- a/codex-lens-v2/README.md +++ b/codex-lens-v2/README.md @@ -31,13 +31,13 @@ That's it. Claude Code will auto-discover the tools: `index_project` → `search ```bash # Standard install (includes vector search + API clients) -pip install codexlens-search +uv pip install codexlens-search # With MCP server for Claude Code -pip install codexlens-search[mcp] +uv pip install codexlens-search[mcp] ``` -Optional extras for advanced use: +Optional extras: | Extra | Description | |-------|-------------| @@ -123,7 +123,7 @@ Format: `url|key|model,url|key|model,...` ### Local Models (Offline, No API) ```bash -pip install codexlens-search[mcp] +uv pip install codexlens-search[mcp] codexlens-search download-models ``` @@ -195,6 +195,8 @@ codexlens-search download-models | `CODEXLENS_FTS_TOP_K` | `50` | FTS results per method | | `CODEXLENS_FUSION_K` | `60` | RRF fusion k parameter | | `CODEXLENS_RERANKER_TOP_K` | `20` | Results to rerank | +| `CODEXLENS_EMBED_BATCH_SIZE` | `32` | Max texts per API batch (auto-splits on 413) | +| `CODEXLENS_EMBED_MAX_TOKENS` | `8192` | Max tokens per text (truncate if exceeded, 0=no limit) | | `CODEXLENS_INDEX_WORKERS` | `2` | Parallel indexing workers | | `CODEXLENS_MAX_FILE_SIZE` | `1000000` | Max file size in bytes | @@ -215,7 +217,7 @@ Query → [Embedder] → query vector ```bash git clone https://github.com/catlog22/codexlens-search.git cd codexlens-search -pip install -e ".[dev]" +uv pip install -e ".[dev]" pytest ``` diff --git a/codex-lens-v2/pyproject.toml b/codex-lens-v2/pyproject.toml index 18384691..9e10e7ea 100644 --- a/codex-lens-v2/pyproject.toml +++ b/codex-lens-v2/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "codexlens-search" -version = "0.3.0" +version = "0.4.1" description = "Lightweight semantic code search engine — 2-stage vector + FTS + RRF fusion + MCP server" requires-python = ">=3.10" dependencies = [ diff --git a/codex-lens-v2/src/codexlens_search/bridge.py b/codex-lens-v2/src/codexlens_search/bridge.py index 2a2e7bc8..42eced7c 100644 --- a/codex-lens-v2/src/codexlens_search/bridge.py +++ b/codex-lens-v2/src/codexlens_search/bridge.py @@ -91,6 +91,8 @@ def create_config_from_env(db_path: str | Path, **overrides: object) -> "Config" kwargs["embed_api_concurrency"] = int(os.environ["CODEXLENS_EMBED_API_CONCURRENCY"]) if os.environ.get("CODEXLENS_EMBED_API_MAX_TOKENS"): kwargs["embed_api_max_tokens_per_batch"] = int(os.environ["CODEXLENS_EMBED_API_MAX_TOKENS"]) + if os.environ.get("CODEXLENS_EMBED_MAX_TOKENS"): + kwargs["embed_max_tokens"] = int(os.environ["CODEXLENS_EMBED_MAX_TOKENS"]) # Reranker API env vars if os.environ.get("CODEXLENS_RERANKER_API_URL"): kwargs["reranker_api_url"] = os.environ["CODEXLENS_RERANKER_API_URL"] diff --git a/codex-lens-v2/src/codexlens_search/config.py b/codex-lens-v2/src/codexlens_search/config.py index 0968411a..6b7dadd8 100644 --- a/codex-lens-v2/src/codexlens_search/config.py +++ b/codex-lens-v2/src/codexlens_search/config.py @@ -10,7 +10,7 @@ class Config: # Embedding embed_model: str = "BAAI/bge-small-en-v1.5" embed_dim: int = 384 - embed_batch_size: int = 64 + embed_batch_size: int = 32 # API embedding (optional — overrides local fastembed when set) embed_api_url: str = "" # e.g. "https://api.openai.com/v1" @@ -19,7 +19,8 @@ class Config: # Multi-endpoint: list of {"url": "...", "key": "...", "model": "..."} dicts embed_api_endpoints: list[dict[str, str]] = None # type: ignore[assignment] embed_api_concurrency: int = 4 - embed_api_max_tokens_per_batch: int = 8192 + embed_api_max_tokens_per_batch: int = 32768 + embed_max_tokens: int = 8192 # max tokens per single text (0 = no limit) # Model download / cache model_cache_dir: str = "" # empty = fastembed default cache diff --git a/codex-lens-v2/src/codexlens_search/embed/api.py b/codex-lens-v2/src/codexlens_search/embed/api.py index 55d4201a..a716fcd2 100644 --- a/codex-lens-v2/src/codexlens_search/embed/api.py +++ b/codex-lens-v2/src/codexlens_search/embed/api.py @@ -95,6 +95,16 @@ class APIEmbedder(BaseEmbedder): """Rough token estimate: ~4 chars per token for code.""" return max(1, len(text) // 4) + def _truncate_text(self, text: str) -> str: + """Truncate text to embed_max_tokens if configured.""" + max_tokens = self._config.embed_max_tokens + if max_tokens <= 0: + return text + max_chars = max_tokens * 4 # inverse of _estimate_tokens + if len(text) > max_chars: + return text[:max_chars] + return text + def _pack_batches( self, texts: list[str] ) -> list[list[tuple[int, str]]]: @@ -189,14 +199,35 @@ class APIEmbedder(BaseEmbedder): # -- Public interface --------------------------------------------- def embed_single(self, text: str) -> np.ndarray: + text = self._truncate_text(text) endpoint = self._next_endpoint() vecs = self._call_api([text], endpoint) return vecs[0] + def _call_api_with_split( + self, + texts: list[str], + endpoint: "_Endpoint", + ) -> list[np.ndarray]: + """Call API with automatic batch splitting on 413 errors.""" + try: + return self._call_api(texts, endpoint) + except Exception as exc: + if "413" in str(exc) and len(texts) > 1: + mid = len(texts) // 2 + logger.info("413 received, splitting batch %d → %d + %d", len(texts), mid, len(texts) - mid) + left = self._call_api_with_split(texts[:mid], endpoint) + right = self._call_api_with_split(texts[mid:], endpoint) + return left + right + raise + def embed_batch(self, texts: list[str]) -> list[np.ndarray]: if not texts: return [] + # 0. Truncate texts exceeding model context + texts = [self._truncate_text(t) for t in texts] + # 1. Pack into token-aware batches packed = self._pack_batches(texts) @@ -205,7 +236,7 @@ class APIEmbedder(BaseEmbedder): batch_texts = [t for _, t in packed[0]] batch_indices = [i for i, _ in packed[0]] endpoint = self._next_endpoint() - vecs = self._call_api(batch_texts, endpoint) + vecs = self._call_api_with_split(batch_texts, endpoint) results: dict[int, np.ndarray] = {} for idx, vec in zip(batch_indices, vecs): results[idx] = vec @@ -220,7 +251,7 @@ class APIEmbedder(BaseEmbedder): batch_texts = [t for _, t in batch] batch_indices = [i for i, _ in batch] endpoint = self._next_endpoint() - future = self._executor.submit(self._call_api, batch_texts, endpoint) + future = self._executor.submit(self._call_api_with_split, batch_texts, endpoint) futures.append(future) batch_index_map.append(batch_indices) diff --git a/codex-lens-v2/src/codexlens_search/indexing/pipeline.py b/codex-lens-v2/src/codexlens_search/indexing/pipeline.py index 368a02c7..b38ad96d 100644 --- a/codex-lens-v2/src/codexlens_search/indexing/pipeline.py +++ b/codex-lens-v2/src/codexlens_search/indexing/pipeline.py @@ -604,6 +604,7 @@ class IndexingPipeline: max_chunk_chars: int = _DEFAULT_MAX_CHUNK_CHARS, chunk_overlap: int = _DEFAULT_CHUNK_OVERLAP, max_file_size: int = 50_000, + progress_callback: callable | None = None, ) -> IndexStats: """Reconcile index state against a current file list. @@ -637,19 +638,38 @@ class IndexingPipeline: for rel in removed: self.remove_file(rel) - # Index new and changed files - total_files = 0 - total_chunks = 0 + # Collect files needing update + files_to_index: list[Path] = [] for rel, fpath in current_rel_paths.items(): - stats = self.index_file( - fpath, + try: + text = fpath.read_text(encoding="utf-8", errors="replace") + except Exception: + continue + content_hash = self._content_hash(text) + if meta.file_needs_update(rel, content_hash): + # Remove old data if previously indexed + if meta.get_file_hash(rel) is not None: + meta.mark_file_deleted(rel) + self._fts.delete_by_path(rel) + files_to_index.append(fpath) + + # Batch index via parallel pipeline + if files_to_index: + # Set starting chunk ID from metadata + start_id = self._next_chunk_id() + batch_stats = self._index_files_with_metadata( + files_to_index, root=root, max_chunk_chars=max_chunk_chars, chunk_overlap=chunk_overlap, - max_file_size=max_file_size, + start_chunk_id=start_id, + progress_callback=progress_callback, ) - total_files += stats.files_processed - total_chunks += stats.chunks_created + total_files = batch_stats.files_processed + total_chunks = batch_stats.chunks_created + else: + total_files = 0 + total_chunks = 0 duration = time.monotonic() - t0 result = IndexStats( @@ -665,6 +685,157 @@ class IndexingPipeline: ) return result + def _index_files_with_metadata( + self, + files: list[Path], + *, + root: Path | None = None, + max_chunk_chars: int = _DEFAULT_MAX_CHUNK_CHARS, + chunk_overlap: int = _DEFAULT_CHUNK_OVERLAP, + start_chunk_id: int = 0, + progress_callback: callable | None = None, + ) -> IndexStats: + """Batch index files using the parallel pipeline, registering metadata. + + Like index_files() but also registers each file and its chunks + in the MetadataStore for incremental tracking. + + Args: + files: Files to index. + root: Root for relative paths. + max_chunk_chars: Max chars per chunk. + chunk_overlap: Overlap between chunks. + start_chunk_id: Starting chunk ID. + progress_callback: Optional callback(files_done, total_files) for progress. + """ + meta = self._require_metadata() + if not files: + return IndexStats() + + t0 = time.monotonic() + + embed_queue: queue.Queue = queue.Queue(maxsize=4) + index_queue: queue.Queue = queue.Queue(maxsize=4) + + worker_errors: list[Exception] = [] + error_lock = threading.Lock() + + def _record_error(exc: Exception) -> None: + with error_lock: + worker_errors.append(exc) + + embed_thread = threading.Thread( + target=self._embed_worker, + args=(embed_queue, index_queue, _record_error), + daemon=True, name="sync-embed", + ) + index_thread = threading.Thread( + target=self._index_worker, + args=(index_queue, _record_error), + daemon=True, name="sync-index", + ) + embed_thread.start() + index_thread.start() + + chunk_id = start_chunk_id + files_processed = 0 + chunks_created = 0 + total_files = len(files) + + # Cross-file chunk accumulator for optimal API batch utilization + max_batch_items = self._config.embed_batch_size + max_batch_tokens = self._config.embed_api_max_tokens_per_batch + buf_ids: list[int] = [] + buf_texts: list[str] = [] + buf_paths: list[str] = [] + buf_lines: list[tuple[int, int]] = [] + buf_tokens = 0 + + def _flush_buffer() -> None: + nonlocal buf_ids, buf_texts, buf_paths, buf_lines, buf_tokens + if buf_ids: + embed_queue.put((list(buf_ids), list(buf_texts), list(buf_paths), list(buf_lines))) + buf_ids.clear() + buf_texts.clear() + buf_paths.clear() + buf_lines.clear() + buf_tokens = 0 + + for fpath in files: + exclude_reason = is_file_excluded(fpath, self._config) + if exclude_reason: + logger.debug("Skipping %s: %s", fpath, exclude_reason) + if progress_callback: + progress_callback(files_processed, total_files) + continue + try: + text = fpath.read_text(encoding="utf-8", errors="replace") + except Exception as exc: + logger.debug("Skipping %s: %s", fpath, exc) + if progress_callback: + progress_callback(files_processed, total_files) + continue + + rel_path = str(fpath.relative_to(root)) if root else str(fpath) + content_hash = self._content_hash(text) + file_chunks = self._smart_chunk(text, rel_path, max_chunk_chars, chunk_overlap) + + if not file_chunks: + meta.register_file(rel_path, content_hash, fpath.stat().st_mtime) + continue + + files_processed += 1 + file_chunk_ids = [] + for chunk_text, path, sl, el in file_chunks: + chunk_tokens = max(1, len(chunk_text) // 4) + # Flush if adding this chunk would exceed batch limits + if buf_ids and ( + len(buf_ids) >= max_batch_items + or buf_tokens + chunk_tokens > max_batch_tokens + ): + _flush_buffer() + + buf_ids.append(chunk_id) + buf_texts.append(chunk_text) + buf_paths.append(path) + buf_lines.append((sl, el)) + buf_tokens += chunk_tokens + file_chunk_ids.append((chunk_id, chunk_text)) + chunk_id += 1 + + chunks_created += len(file_chunk_ids) + + # Register metadata per file + meta.register_file(rel_path, content_hash, fpath.stat().st_mtime) + chunk_id_hashes = [ + (cid, self._content_hash(ct)) for cid, ct in file_chunk_ids + ] + meta.register_chunks(rel_path, chunk_id_hashes) + + if progress_callback: + progress_callback(files_processed, total_files) + + # Final flush for remaining chunks + _flush_buffer() + + embed_queue.put(_SENTINEL) + embed_thread.join() + index_thread.join() + + self._binary_store.save() + self._ann_index.save() + + duration = time.monotonic() - t0 + + if worker_errors: + raise worker_errors[0] + + return IndexStats( + files_processed=files_processed, + chunks_created=chunks_created, + duration_seconds=round(duration, 2), + ) + def compact(self) -> None: """Rebuild indexes excluding tombstoned chunk IDs. diff --git a/codex-lens-v2/src/codexlens_search/mcp_server.py b/codex-lens-v2/src/codexlens_search/mcp_server.py index d292042a..37ac6df6 100644 --- a/codex-lens-v2/src/codexlens_search/mcp_server.py +++ b/codex-lens-v2/src/codexlens_search/mcp_server.py @@ -58,11 +58,12 @@ Tuning: CODEXLENS_BINARY_TOP_K, _ANN_TOP_K, _FTS_TOP_K, _FUSION_K, """ from __future__ import annotations +import asyncio import logging import threading from pathlib import Path -from mcp.server.fastmcp import FastMCP +from mcp.server.fastmcp import Context, FastMCP from codexlens_search.bridge import ( DEFAULT_EXCLUDES, @@ -139,8 +140,9 @@ def search_code(project_path: str, query: str, top_k: int = 10) -> str: # --------------------------------------------------------------------------- @mcp.tool() -def index_project( - project_path: str, glob_pattern: str = "**/*", force: bool = False +async def index_project( + project_path: str, glob_pattern: str = "**/*", force: bool = False, + ctx: Context | None = None, ) -> str: """Build or rebuild the search index for a project. @@ -167,7 +169,27 @@ def index_project( if p.is_file() and not should_exclude(p.relative_to(root), DEFAULT_EXCLUDES) ] - stats = indexing.sync(file_paths, root=root) + if ctx: + await ctx.report_progress(0, len(file_paths), f"Scanning {len(file_paths)} files...") + + # Progress callback bridging sync pipeline → async MCP context + loop = asyncio.get_event_loop() + + def _progress(done: int, total: int) -> None: + if ctx: + asyncio.run_coroutine_threadsafe( + ctx.report_progress(done, total, f"Indexed {done}/{total} files"), + loop, + ) + + stats = indexing.sync(file_paths, root=root, progress_callback=_progress) + + if ctx: + await ctx.report_progress( + stats.files_processed, stats.files_processed, + f"Done: {stats.files_processed} files, {stats.chunks_created} chunks" + ) + return ( f"Indexed {stats.files_processed} files, " f"{stats.chunks_created} chunks in {stats.duration_seconds:.1f}s. " @@ -208,7 +230,10 @@ def index_status(project_path: str) -> str: @mcp.tool() -def index_update(project_path: str, glob_pattern: str = "**/*") -> str: +async def index_update( + project_path: str, glob_pattern: str = "**/*", + ctx: Context | None = None, +) -> str: """Incrementally sync the index with current project files. Only re-indexes files that changed since last indexing. @@ -231,7 +256,19 @@ def index_update(project_path: str, glob_pattern: str = "**/*") -> str: if p.is_file() and not should_exclude(p.relative_to(root), DEFAULT_EXCLUDES) ] - stats = indexing.sync(file_paths, root=root) + if ctx: + await ctx.report_progress(0, len(file_paths), f"Scanning {len(file_paths)} files...") + + loop = asyncio.get_event_loop() + + def _progress(done: int, total: int) -> None: + if ctx: + asyncio.run_coroutine_threadsafe( + ctx.report_progress(done, total, f"Synced {done}/{total} files"), + loop, + ) + + stats = indexing.sync(file_paths, root=root, progress_callback=_progress) return ( f"Synced {stats.files_processed} files, " f"{stats.chunks_created} chunks in {stats.duration_seconds:.1f}s."