agestra 4.3.5 → 4.4.0

package/README.zh.md

@@ -0,0 +1,328 @@
+# Agestra
+
+[![npm version](https://img.shields.io/npm/v/agestra.svg)](https://www.npmjs.com/package/agestra)
+[![license](https://img.shields.io/npm/l/agestra.svg)](LICENSE)
+
+**Agent + Orchestra** — 一个在 Claude Code 中编排多个 AI 提供方的插件。
+
+[English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [中文](README.zh.md)
+
+Agestra 将 Ollama（本地）、Gemini CLI 和 Codex CLI 作为可插拔提供方接入 Claude Code，通过 42 个 MCP 工具提供多 AI 编排、独立汇总、共识辩论、自主 CLI Worker、并行任务分发、交叉验证、基于质量的提供方路由，以及持久化 GraphRAG 记忆系统。
+
+## 快速开始
+
+在 Claude Code 中运行：
+
+```
+/plugin marketplace add mua-vtuber/Agestra
+/plugin install agestra@agestra
+```
+
+就这些。Agestra 会在首次使用时通过 `environment_check` 自动检测可用的提供方（Ollama、Gemini CLI、Codex CLI）。
+
+### 前置条件
+
+至少需要安装一个 AI 提供方：
+
+| 提供方 | 安装 | 类型 |
+|--------|------|------|
+| [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | Local LLM |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | Cloud |
+| [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | Cloud |
+
+可选但推荐：
+- **tmux** — 让你在自主执行期间可视化查看 CLI Worker 面板
+
+---
+
+## 理念
+
+**Multi-AI 的目标是验证，而不是节省 token。** 代码审查、设计探索和想法生成工作流都被设计成验证流程，核心不是为了更快并行，而是让多个 AI 提供方独立给出意见，从而发现盲点。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `/agestra review [target]` | 审查代码质量、安全性和集成完成度 |
+| `/agestra idea [topic]` | 通过与相似项目对比发掘改进点 |
+| `/agestra design [subject]` | 在实现前探索架构与设计取舍 |
+| `/agestra implement [task]` | 以 Claude only 或 Multi-AI 模式执行实现 |
+
+每个命令都会提供模式选择：
+
+| 模式 | 说明 |
+|------|------|
+| **Claude only** | 由插件专用代理独立完成 |
+| **각자 독립** (Independent) | 每个 AI 独立完成，随后由主持者汇总成统一文档 |
+| **끝장토론** (Debate) | 独立产出 + 文档审阅轮次，直到所有 AI 达成一致 |
+
+## 代理
+
+| 代理 | 模型 | 角色 |
+|------|------|------|
+| `agestra-team-lead` | Sonnet | 全局编排者：环境检查、按质量路由提供方、选择工作模式、监督 CLI Worker、驱动 QA 循环 |
+| `agestra-reviewer` | Opus | 严格质量审查者：关注安全、孤立实现、规格漂移、测试缺口 |
+| `agestra-designer` | Opus | 架构探索者：苏格拉底式提问、权衡分析 |
+| `agestra-ideator` | Sonnet | 改进点发现者：Web 调研、竞品分析 |
+| `agestra-moderator` | Sonnet | 多模式主持者：带共识检测的辩论、独立汇总、文档审查、冲突解决 |
+| `agestra-qa` | Opus | QA 验证者：检查设计符合性并给出 PASS/FAIL 判断 |
+
+## 技能
+
+| 技能 | 说明 |
+|------|------|
+| `provider-guide` | 提供方路由、模式参考、编排流水线 |
+| `worker-manage` | 列出、检查、收集和停止 CLI Worker |
+| `cancel` | 安全停止 worker、辩论、链路和任务 |
+| `build-fix` | 自动诊断并修复 build/typecheck/lint 错误 |
+| `trace` | 查看代理执行时间线与流程图 |
+| `design` | 包含 Multi-AI 模式选择的架构探索工作流 |
+| `idea` | 包含 Multi-AI 模式选择的改进发现工作流 |
+
+---
+
+## 架构
+
+这是一个包含 8 个包的 Turborepo monorepo：
+
+| 包 | 说明 |
+|----|------|
+| `@agestra/core` | `AIProvider` 接口、基于难度的路由注册表、配置加载、CLI runner、原子写入、任务队列、密钥扫描、worktree 管理、任务清单、CLI Worker 管理器 |
+| `@agestra/provider-ollama` | 带模型检测的 Ollama HTTP 适配器 |
+| `@agestra/provider-gemini` | Google Gemini CLI 适配器 |
+| `@agestra/provider-codex` | OpenAI Codex CLI 适配器 |
+| `@agestra/agents` | 带共识检测的辩论引擎、轮次质量评估、任务分发、交叉验证、任务链、自动 QA、文件变更跟踪、会话管理 |
+| `@agestra/workspace` | 用于评审、分析笔记和汇总报告的工作区文档管理器 |
+| `@agestra/memory` | GraphRAG：FTS5 + 向量 + 知识图谱混合检索，以及死路追踪 |
+| `@agestra/mcp-server` | MCP 协议层，42 个工具，按环境过滤工具并动态分发 |
+
+### 设计原则
+
+- **Provider abstraction** — 所有后端都实现 `AIProvider`（`chat`、`healthCheck`、`getCapabilities`）。新增提供方只需新增一个 provider 包并注册工厂。
+- **Zero-config** — 启动时自动检测提供方，无需手动配置。
+- **Plugin-native** — 以 Claude Code 插件形式安装，Skills、hooks 和 MCP server 一起打包。
+- **Modular dispatch** — 每类工具都是独立模块，对外提供 `getTools()` 和 `handleTool()`。服务端负责动态收集与分发。
+- **Atomic writes** — 所有文件操作都采用“写临时文件再重命名”的方式，避免损坏。
+- **Dead-end tracking** — 失败方案会记录到 GraphRAG 中，并注入后续提示词。
+- **Preflight security** — 启动 CLI Worker 前会进行密钥扫描，并使用数组参数启动进程以防注入。
+
+### 工作模式
+
+**文本工作**（review、design、idea）：Claude only → 각자 독립 → 끝장토론
+
+**实现工作**（team-lead orchestration）：
+- **Claude만으로** — Claude 直接结合项目/全局代理完成实现。
+- **다른 AI도 함께** — CLI Worker（Codex/Gemini）在隔离的 git worktree 中自主编码，Ollama 处理简单任务，Claude 负责监督与合并。
+
+---
+
+## 工具（42）
+
+### AI Chat（3）
+
+| 工具 | 说明 |
+|------|------|
+| `ai_chat` | 与指定提供方对话（使用 `"auto"` 可启用基于质量的路由）；如有需要，可通过 `save_as_document` 将回复保存为文档 |
+| `ai_analyze_files` | 从磁盘读取文件并连同问题一起发送给提供方 |
+| `ai_compare` | 将同一提示发送给多个提供方并比较结果 |
+
+### Agent Orchestration（11）
+
+| 工具 | 说明 |
+|------|------|
+| `agent_debate_start` | 启动多提供方辩论（非阻塞，可选质量循环 + 验证者） |
+| `agent_debate_status` | 查看辩论状态与转录 |
+| `agent_debate_create` | 创建回合制辩论会话（返回 debate ID） |
+| `agent_debate_turn` | 执行某个提供方的一回合；支持 `provider: "claude"` 让 Claude 独立参与 |
+| `agent_debate_conclude` | 结束辩论并生成最终转录 |
+| `agent_debate_moderate` | 运行全自动辩论：创建会话、执行专家代理轮次、检测共识，仅返回摘要 |
+| `agent_debate_review` | 将文档发送给多个提供方进行独立审查 |
+| `agent_cross_validate` | 对输出进行交叉验证（仅限 agent-tier validators） |
+| `agent_changes_review` | 审查隔离任务中的文件变更 |
+| `agent_changes_accept` | 接受并合并隔离任务中的变更 |
+| `agent_changes_reject` | 拒绝变更并清理隔离 worktree |
+
+### CLI Workers（4）
+
+| 工具 | 说明 |
+|------|------|
+| `cli_worker_spawn` | 以自主模式启动 CLI AI（Codex/Gemini），带 git worktree 隔离与预检安全机制 |
+| `cli_worker_status` | 查看 worker 的 FSM 状态、heartbeat 和输出尾部 |
+| `cli_worker_collect` | 收集已完成 worker 的结果（git diff、输出、退出码） |
+| `cli_worker_stop` | 停止运行中的 worker（SIGTERM → SIGKILL）并清理 worktree |
+
+### Environment（1）
+
+| 工具 | 说明 |
+|------|------|
+| `environment_check` | 检测 CLI 工具、带分层信息的 Ollama 模型、tmux、git worktree 支持与可用模式 |
+
+### Workspace（7）
+
+| 工具 | 说明 |
+|------|------|
+| `workspace_create_review` | 创建包含文件与规则的代码审查文档 |
+| `workspace_request_review` | 请求提供方审查某个文档 |
+| `workspace_review_status` | 查看审查完成状态 |
+| `workspace_add_comment` | 为审查添加评论 |
+| `workspace_create_document` | 创建带标题、Markdown 正文和可选元数据的通用工作区文档 |
+| `workspace_read` | 读取文档内容 |
+| `workspace_list` | 列出工作区中的全部文档 |
+
+### Provider Management（2）
+
+| 工具 | 说明 |
+|------|------|
+| `provider_list` | 列出提供方及其状态和能力 |
+| `provider_health` | 对一个或全部提供方进行健康检查 |
+
+### Ollama（2）
+
+| 工具 | 说明 |
+|------|------|
+| `ollama_models` | 列出已安装模型及其大小和分层 |
+| `ollama_pull` | 下载模型 |
+
+### Memory（6）
+
+| 工具 | 说明 |
+|------|------|
+| `memory_search` | 混合检索（FTS5 + 向量 + 图） |
+| `memory_index` | 将文件/目录索引进记忆系统 |
+| `memory_store` | 存储知识节点（fact、decision、dead_end、finding） |
+| `memory_dead_ends` | 搜索过去失败的方法，避免重复踩坑 |
+| `memory_context` | 在 token 预算内组装相关上下文 |
+| `memory_add_edge` | 为知识节点之间创建关系边 |
+
+### Jobs（2）
+
+| 工具 | 说明 |
+|------|------|
+| `cli_job_submit` | 将长时间运行的 CLI 任务提交到后台 |
+| `cli_job_status` | 查看任务状态与输出 |
+
+### QA（1）
+
+| Tool | Description |
+|------|-------------|
+| `qa_run` | 自动检测 build/test 命令并运行 QA，输出 PASS/FAIL 摘要 |
+
+### Trace / Observability（3）
+
+| Tool | Description |
+|------|-------------|
+| `trace_query` | 按条件查询 trace 记录（提供方、任务、时间范围） |
+| `trace_summary` | 获取各提供方的质量统计、性能指标和难度资格 |
+| `trace_visualize` | 生成某次追踪操作流程的 Mermaid 图 |
+
+---
+
+## 配置
+
+### providers.config.json（可选）
+
+Agestra 会在启动时自动检测提供方。如果需要手动控制，可在项目根目录创建 `providers.config.json`：
+
+| 字段 | 说明 |
+|------|------|
+| `defaultProvider` | 未指定时使用的提供方 ID |
+| `providers[].id` | 唯一标识符 |
+| `providers[].type` | `ollama`、`gemini-cli` 或 `codex-cli` |
+| `providers[].enabled` | 是否在启动时加载 |
+| `providers[].config` | 类型相关配置（host、timeout 等） |
+
+### 运行时数据
+
+保存在 `.agestra/` 下（已加入 gitignore）：
+
+| 路径 | 用途 |
+|------|------|
+| `.agestra/sessions/` | 辩论与任务会话状态 |
+| `.agestra/workspace/` | 工作区文档（评审、笔记、报告） |
+| `.agestra/memory.db` | GraphRAG SQLite 数据库 |
+| `.agestra/.jobs/` | 后台任务队列 |
+| `.agestra/.workers/` | CLI Worker 状态、清单和输出日志 |
+| `.agestra/worktrees/` | 用于隔离 CLI Worker 执行的 git worktree |
+| `.agestra/traces/` | 提供方 trace JSONL（30 天后自动清理） |
+
+---
+
+## 开发
+
+```bash
+npm install        # 安装依赖
+npm run build      # 构建所有包（Turborepo）
+npm test           # 运行全部测试（Vitest）
+npm run bundle     # 构建单文件插件包（esbuild）
+npm run dev        # 监听模式
+npm run lint       # Lint（ESLint）
+npm run clean      # 删除 dist/
+```
+
+### 项目结构
+
+```
+agestra/
+├── .claude-plugin/
+│   ├── plugin.json          # Claude Code 插件清单
+│   └── marketplace.json     # 插件市场元数据
+├── commands/
+│   ├── review.md            # /agestra review — 质量验证
+│   ├── idea.md              # /agestra idea — 改进点发现
+│   ├── design.md            # /agestra design — 架构探索
+│   └── implement.md         # /agestra implement — 实现工作流
+├── agents/
+│   ├── agestra-reviewer.md  # 严格质量审查者（Opus）
+│   ├── agestra-designer.md  # 架构探索者（Opus）
+│   ├── agestra-ideator.md   # 改进点发现者（Sonnet）
+│   ├── agestra-moderator.md # 多模式主持者（Sonnet）
+│   ├── agestra-qa.md        # QA 验证者（Opus，不写代码）
+│   └── agestra-team-lead.md # 全局编排者（Sonnet，不写代码）
+├── skills/
+│   ├── provider-guide.md    # 提供方路由与模式说明
+│   ├── worker-manage.md     # CLI Worker 管理
+│   ├── cancel.md            # 安全取消操作
+│   ├── build-fix.md         # 构建错误自动修复
+│   └── trace.md             # 执行时间线查看器
+├── hooks/
+│   └── user-prompt-submit.md  # 工具推荐 hook
+├── dist/
+│   └── bundle.js            # 单文件 MCP Server bundle
+├── scripts/
+│   └── bundle.mjs           # esbuild bundle 脚本
+├── packages/
+│   ├── core/                # AIProvider 接口、注册表、安全、worker
+│   ├── provider-ollama/     # Ollama HTTP 适配器
+│   ├── provider-gemini/     # Gemini CLI 适配器
+│   ├── provider-codex/      # Codex CLI 适配器
+│   ├── agents/              # 辩论引擎、分发器、交叉验证器
+│   ├── workspace/           # 工作区文档管理器
+│   ├── memory/              # GraphRAG：混合检索、死路追踪
+│   └── mcp-server/          # MCP Server，42 个工具，按环境过滤并分发
+├── package.json             # 工作区根目录
+└── turbo.json               # Turborepo pipeline
+```
+
+### 添加新提供方
+
+1. 创建 `packages/provider-<name>/` 并实现 `AIProvider`。
+2. 在 `packages/mcp-server/src/index.ts` 中注册工厂。
+3. `npm run build && npm test`
+
+---
+
+## 卸载
+
+在 Claude Code 中：
+
+```
+/plugin uninstall agestra@agestra
+```
+
+插件本身会被干净移除。如果还想删除生成的项目数据，请手动删除 `.agestra/` 目录。
+
+---
+
+## 许可证
+
+[GPL-3.0](LICENSE)

package/agents/agestra-moderator.md

@@ -30,14 +30,14 @@ You operate in one of four modes depending on how you are invoked:
 
 ### Mode: Debate (Traditional)
 
-### Phase 1: Setup
-**Preferred:** Call `agent_debate_moderate` with the topic, providers, and optional goal. This handles the full lifecycle — creating the debate, running rounds, checking consensus, and concluding — and returns only the final summary without consuming main context.
-
-**Manual mode (when fine-grained control is needed):**
-1. Receive the debate topic and specialist context from the invoking command.
-2. Call `provider_list` to check which external providers are available.
-3. Call `agent_debate_create` with the topic and available providers.
-4. Note the debate ID for subsequent turns.
+### Phase 1: Setup
+**Preferred:** Call `agent_debate_moderate` with the topic, providers, and optional goal. This handles the full lifecycle — creating the debate, running rounds, checking consensus, and concluding — and returns only the final summary without consuming main context.
+
+**Manual mode (when fine-grained control is needed):**
+1. Receive the debate topic and specialist context from the invoking command.
+2. Call `provider_list` to check which external providers are available.
+3. Call `agent_debate_create` with the topic and available providers.
+4. Note the debate ID for subsequent turns.
 
 ### Phase 2: Rounds
 For each round (up to 5 maximum):
@@ -62,13 +62,13 @@ For each available provider (e.g., gemini, ollama):
 
 3. The moderator remains neutral — it relays the specialist's work without modifying or editorializing.
 
-**Round summary:**
-After all turns in a round:
-- The system automatically checks for consensus after each turn
-- Consensus is detected when ALL participants explicitly express agreement (e.g., "I agree", "동의합니다", "同意します")
-- If consensus is reached, the system recommends concluding the debate
-- If partial consensus is detected, the system reports which participants have agreed and which are still pending
-- If no consensus, frame the next round's focus based on remaining disagreements
+**Round summary:**
+After all turns in a round:
+- The system automatically checks for consensus after each turn
+- Consensus is detected when ALL participants explicitly express agreement (e.g., "I agree", "동의합니다", "同意します")
+- If consensus is reached, the system recommends concluding the debate
+- If partial consensus is detected, the system reports which participants have agreed and which are still pending
+- If no consensus, frame the next round's focus based on remaining disagreements
 
 ### Phase 3: Conclude
 - Call `agent_debate_conclude` with a comprehensive summary including:
@@ -87,15 +87,18 @@ After all turns in a round:
 
 Invoked when multiple AIs have independently analyzed the same target and their results need to be merged into a unified document.
 
-**Input:** Array of results from all AIs, including Claude's specialist agent output. Each result is tagged with its source provider.
+**Input:** Document ID list of per-provider analysis documents + results tagged by source provider.
 
 **Process:**
 
-1. Read all results carefully.
+1. **Read all individual documents** via `workspace_read` using each document ID.
 2. **Identify common findings** — mentioned by 2+ AIs. These form the consensus core.
 3. **Identify unique findings** — mentioned by only 1 AI. These are notable perspectives.
 4. **Identify contradictions** — AIs that disagree on the same point.
-5. Generate integrated document in this structure:
+5. **Create aggregated document** via `workspace_create_document`:
+   - **title:** `Integrated Analysis — {task summary}`
+   - **metadata:** `{ "Mode": "Independent Aggregation", "Sources": "{comma-separated provider names}", "Source Documents": "{comma-separated document IDs}" }`
+   - **content:** The integrated analysis in this structure:
 
 ```markdown
 ## Integrated Analysis
@@ -115,9 +118,20 @@ Invoked when multiple AIs have independently analyzed the same target and their
 
 ### Summary
 [unified recommendation considering all perspectives]
+
+### Source Documents
+- {provider}: {document ID}
+- {provider}: {document ID}
 ```
 
-6. Present the integrated document. Do NOT favor any provider's findings over others.
+6. Do NOT favor any provider's findings over others.
+
+7. **Report to user** with a concise summary:
+   - Key consensus findings (1-3 lines)
+   - Notable unique findings (if any)
+   - Disputed points (if any)
+   - List of individual document IDs for reference
+   - Aggregated document ID for the full integrated analysis
 
 </Workflow_Independent_Aggregation>
 
@@ -125,11 +139,11 @@ Invoked when multiple AIs have independently analyzed the same target and their
 
 ### Mode: Document Review Round (Debate Phase 2)
 
-Invoked after Independent Aggregation has produced an initial document. The document is iteratively reviewed by all AIs until consensus or max rounds.
+Invoked after Independent Aggregation has produced an initial document. The document is iteratively reviewed by all AIs until consensus.
 
 **Input:** Current document + list of participating providers.
 
-**Process (per round, max 5 rounds):**
+**Process (per round, no maximum — until all agree):**
 
 1. Send the current document to each AI for review:
    - **Claude:** Spawn the appropriate specialist agent → analyze document → produce feedback.
@@ -155,7 +169,7 @@ Invoked after Independent Aggregation has produced an initial document. The docu
 6. **Consensus check:**
    - All AIs agree on all sections → consensus reached. Proceed to final document.
    - Disagreements remain → next round with the revised document.
-   - After 5 rounds with no full consensus → conclude with split positions documented.
+   - **Every 10 rounds:** Ask the user via AskUserQuestion whether to continue or stop with the current state. If the user stops, conclude with split positions documented.
 
 7. Return: revised document + consensus map.
 
@@ -233,7 +247,7 @@ If after 5 rounds no consensus:
 </Consensus_Criteria>
 
 <Constraints>
-- Maximum 5 rounds. If consensus is not reached by round 5, conclude with disagreements documented.
+- No maximum rounds — continue until all participants agree. Every 10 rounds, ask the user whether to continue or stop with the current state.
 - Do NOT express your own opinion on the debate topic. You are a facilitator, not a participant.
 - Do NOT skip Claude's turn. Claude's independent participation (via the specialist agent's perspective) is a core feature.
 - Summarize neutrally. Do not favor any provider's position.
@@ -242,12 +256,15 @@ If after 5 rounds no consensus:
 - Communicate in the user's language.
 </Constraints>
 
-<Tool_Usage>
-- `provider_list` — check available providers at the start
-- `agent_debate_moderate` — **recommended entry point**: run a fully moderated debate with automatic consensus detection and specialist selection. Handles full lifecycle and returns only the final summary.
-- `agent_debate_create` — create a debate session manually (use when you need fine-grained turn control)
-- `agent_debate_turn` — execute each provider's turn (manual mode only)
-- `agent_debate_conclude` — end the debate with summary (manual mode only)
-- `agent_debate_review` — send a document to providers for structured review (Document Review mode)
-- `ai_chat` — query individual providers for feedback (Independent Aggregation mode)
-</Tool_Usage>
+<Tool_Usage>
+- `provider_list` — check available providers at the start
+- `agent_debate_moderate` — **recommended entry point**: run a fully moderated debate with automatic consensus detection and specialist selection. Handles full lifecycle and returns only the final summary.
+- `agent_debate_create` — create a debate session manually (use when you need fine-grained turn control)
+- `agent_debate_turn` — execute each provider's turn (manual mode only)
+- `agent_debate_conclude` — end the debate with summary (manual mode only)
+- `agent_debate_review` — send a document to providers for structured review (Document Review mode)
+- `ai_chat` — query individual providers for feedback (Independent Aggregation mode)
+- `workspace_create_document` — create analysis or aggregated documents (Independent Aggregation mode)
+- `workspace_read` — read individual provider documents by ID (Independent Aggregation mode)
+- `workspace_add_comment` — append feedback or updates to existing documents
+</Tool_Usage>

package/commands/design.md

@@ -36,8 +36,8 @@ Use AskUserQuestion to present these options (in the user's language):
 | Option | Condition | Description |
 |--------|-----------|-------------|
 | **Claude only** | Always | 플러그인 전문 에이전트가 소크라테스식 질문으로 아키텍처 탐색 |
-| **각자 독립** | 1+ provider available | 각 AI가 독립적으로 아키텍처 제안 → 진행자가 취합하여 문서 작성 |
-| **끝장토론** | 1+ provider available | 각자 독립 + 문서를 돌아가며 분석/피드백, 모두 동의할 때까지 |
+| **각자 독립** | 1+ provider available | 에이전트 팀(moderator + designer + 외부 AI)이 각자 독립 설계 후 취합 문서 작성 |
+| **끝장토론** | 1+ provider available | 각자 독립 설계 후 취합 문서를 돌아가며 분석/피드백, 모두 동의할 때까지 |
 
 Only show options whose conditions are met. If no providers are available, skip and run Claude only.
 
@@ -47,26 +47,47 @@ Only show options whose conditions are met. If no providers are available, skip
 Spawn the `agestra-designer` agent with the subject as context. The designer will ask questions to understand intent, explore the codebase for existing patterns, propose 2-3 approaches with trade-offs, refine based on feedback, and produce a design document in `docs/plans/`.
 
 ### If "각자 독립":
+
+**팀 구성:** `agestra-moderator` (리더) + `agestra-designer` (Claude) + 사용 가능한 외부 AI (gemini, codex, ollama 등)
+
 1. In parallel:
    - Spawn the `agestra-designer` agent for Claude's independent architecture exploration.
-   - For each available provider, call `ai_chat` with this prompt:
+     After the agent completes, save Claude's result as a document via `workspace_create_document`:
+     - **title:** `Architecture Design — claude/designer`
+     - **metadata:** `{ "Provider": "claude/designer", "Task": "{subject}", "Mode": "Independent" }`
+     - **content:** The designer agent's full output.
+   - For each available provider, call `ai_chat` with `save_as_document` to let each AI produce its own document directly:
+     - **save_as_document.title:** `Architecture Design — {provider}`
+     - **save_as_document.metadata:** `{ "Task": "{subject}", "Mode": "Independent" }`
+     - **prompt:**
+
+       > Propose an architecture approach for [subject]. Consider existing patterns in the codebase, trade-offs (complexity, performance, maintainability), and implementation steps. Present 2-3 distinct approaches with pros/cons for each.
+       >
+       > Subject: [the design subject]
 
-     > Propose an architecture approach for [subject]. Consider existing patterns in the codebase, trade-offs (complexity, performance, maintainability), and implementation steps. Present 2-3 distinct approaches with pros/cons for each.
-     >
-     > Subject: [the design subject]
+2. Collect all document IDs from step 1.
 
-2. Collect all results (Claude's designer output + each provider's response).
 3. Spawn the `agestra-moderator` agent in **Independent Aggregation** mode:
-   - Pass ALL results as input, tagged by source provider.
+   - Pass the **document ID list**.
+   - Moderator reads each document via `workspace_read`.
    - Moderator classifies: consensus approaches, unique ideas, disputed trade-offs.
-   - Moderator generates an integrated architecture document.
-4. Present the integrated document to the user.
+   - Moderator creates an **aggregated document** via `workspace_create_document`.
+
+4. Present a **summary report** to the user:
+   - Key consensus approaches (1-3 lines).
+   - Notable unique design ideas (if any).
+   - Trade-off disagreements (if any).
+   - Individual document IDs for reference.
+   - Aggregated document ID for the full integrated analysis.
 
 ### If "끝장토론":
+
+**팀 구성:** `agestra-moderator` (리더) + `agestra-designer` (Claude) + 사용 가능한 외부 AI (gemini, codex, ollama 등)
+
 1. Execute "각자 독립" steps 1-3 above (independent work + initial aggregation).
    - The moderator's integrated document becomes the starting document.
 
-2. Document review rounds (max 5):
+2. Document review rounds (no max — until all agree):
    a. Moderator sends the current document to each AI for review:
       - Claude: spawn `agestra-designer` → analyze document → write section-by-section feedback
       - Other providers: `agent_debate_turn` with the document as prompt, requesting agree/disagree per section
@@ -75,6 +96,7 @@ Spawn the `agestra-designer` agent with the subject as context. The designer wil
    d. Revise document incorporating disagreement feedback.
    e. If all providers agree on all sections → consensus reached.
    f. If not → next round with revised document.
+   g. **Every 10 rounds:** Ask the user via AskUserQuestion whether to continue or stop with current state.
 
 3. Present the final document:
    - Consensus sections: marked as agreed

package/commands/idea.md

@@ -25,8 +25,8 @@ Use AskUserQuestion to present these options (in the user's language):
 | Option | Condition | Description |
 |--------|-----------|-------------|
 | **Claude only** | Always | 플러그인 전문 에이전트가 단독으로 개선점 탐색 |
-| **각자 독립** | 1+ provider available | 각 AI가 독립적으로 개선점 탐색 → 진행자가 취합하여 문서 작성 |
-| **끝장토론** | 1+ provider available | 각자 독립 + 문서를 돌아가며 분석/피드백, 모두 동의할 때까지 |
+| **각자 독립** | 1+ provider available | 에이전트 팀(moderator + ideator + 외부 AI)이 각자 독립 탐색 후 취합 문서 작성 |
+| **끝장토론** | 1+ provider available | 각자 독립 탐색 후 취합 문서를 돌아가며 분석/피드백, 모두 동의할 때까지 |
 
 Only show options whose conditions are met. If no providers are available, skip and run Claude only.
 
@@ -36,26 +36,47 @@ Only show options whose conditions are met. If no providers are available, skip
 Spawn the `agestra-ideator` agent with the topic as context. The ideator will research similar projects, collect user complaints, build feature comparisons, and generate prioritized recommendations.
 
 ### If "각자 독립":
+
+**팀 구성:** `agestra-moderator` (리더) + `agestra-ideator` (Claude) + 사용 가능한 외부 AI (gemini, codex, ollama 등)
+
 1. In parallel:
    - Spawn the `agestra-ideator` agent for Claude's independent improvement research.
-   - For each available provider, call `ai_chat` with this prompt:
+     After the agent completes, save Claude's result as a document via `workspace_create_document`:
+     - **title:** `Idea Exploration — claude/ideator`
+     - **metadata:** `{ "Provider": "claude/ideator", "Task": "{topic}", "Mode": "Independent" }`
+     - **content:** The ideator agent's full output.
+   - For each available provider, call `ai_chat` with `save_as_document` to let each AI produce its own document directly:
+     - **save_as_document.title:** `Idea Exploration — {provider}`
+     - **save_as_document.metadata:** `{ "Task": "{topic}", "Mode": "Independent" }`
+     - **prompt:**
+
+       > Research improvements for [topic]. Look at similar projects, common user complaints, missing features, and opportunities. For each suggestion, provide: title, category (UX/Performance/Feature/Integration/DX), source of the idea, priority (HIGH/MEDIUM/LOW), and a brief description.
+       >
+       > Topic: [the topic]
 
-     > Research improvements for [topic]. Look at similar projects, common user complaints, missing features, and opportunities. For each suggestion, provide: title, category (UX/Performance/Feature/Integration/DX), source of the idea, priority (HIGH/MEDIUM/LOW), and a brief description.
-     >
-     > Topic: [the topic]
+2. Collect all document IDs from step 1.
 
-2. Collect all results (Claude's ideator output + each provider's response).
 3. Spawn the `agestra-moderator` agent in **Independent Aggregation** mode:
-   - Pass ALL results as input, tagged by source provider.
+   - Pass the **document ID list**.
+   - Moderator reads each document via `workspace_read`.
    - Moderator classifies: consensus suggestions, unique ideas, disputed priorities.
-   - Moderator generates an integrated improvement document.
-4. Present the integrated document to the user.
+   - Moderator creates an **aggregated document** via `workspace_create_document`.
+
+4. Present a **summary report** to the user:
+   - Key consensus suggestions (1-3 lines).
+   - Notable unique ideas (if any).
+   - Priority disagreements (if any).
+   - Individual document IDs for reference.
+   - Aggregated document ID for the full integrated analysis.
 
 ### If "끝장토론":
+
+**팀 구성:** `agestra-moderator` (리더) + `agestra-ideator` (Claude) + 사용 가능한 외부 AI (gemini, codex, ollama 등)
+
 1. Execute "각자 독립" steps 1-3 above (independent work + initial aggregation).
    - The moderator's integrated document becomes the starting document.
 
-2. Document review rounds (max 5):
+2. Document review rounds (no max — until all agree):
    a. Moderator sends the current document to each AI for review:
       - Claude: spawn `agestra-ideator` → analyze document → write section-by-section feedback
       - Other providers: `agent_debate_turn` with the document as prompt, requesting agree/disagree per section
@@ -64,6 +85,7 @@ Spawn the `agestra-ideator` agent with the topic as context. The ideator will re
    d. Revise document incorporating disagreement feedback.
    e. If all providers agree on all sections → consensus reached.
    f. If not → next round with revised document.
+   g. **Every 10 rounds:** Ask the user via AskUserQuestion whether to continue or stop with current state.
 
 3. Present the final document:
    - Consensus sections: marked as agreed