agestra 4.1.1 → 4.3.0

package/.claude-plugin/marketplace.json

@@ -10,12 +10,9 @@
   "plugins": [
     {
       "name": "agestra",
-      "source": {
-        "source": "npm",
-        "package": "agestra"
-      },
+      "source": "./",
       "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
-      "version": "4.1.1",
+      "version": "4.3.0",
       "author": {
         "name": "mua-vtuber"
       },

package/.claude-plugin/plugin.json

@@ -1,11 +1,13 @@
-{
-  "name": "agestra",
-  "version": "4.1.1",
-  "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
-  "mcpServers": {
-    "agestra": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/bundle.js"]
-    }
-  }
-}
+{
+  "name": "agestra",
+  "version": "4.3.0",
+  "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, cross-validation, and GraphRAG memory",
+  "mcpServers": {
+    "agestra": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/dist/bundle.js"
+      ]
+    }
+  }
+}

package/README.ko.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md)
 
-Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 멀티에이전트 토론, 병렬 작업 분배, 교차 검증, 지속적 GraphRAG 메모리 시스템을 39개 MCP 도구로 제공합니다.
+Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 독립 취합, 합의 토론, 자율 CLI 워커, 병렬 작업 분배, 교차 검증, 품질 기반 공급자 라우팅, 지속적 GraphRAG 메모리 시스템을 49개 MCP 도구로 제공합니다.
 
 ## 빠른 시작
 
@@ -18,7 +18,7 @@ Claude Code에서 실행:
 /plugin install agestra@agestra
 ```
 
-끝. Agestra가 첫 사용 시 사용 가능한 공급자(Ollama, Gemini CLI, Codex CLI)를 자동 감지합니다.
+끝. Agestra가 첫 사용 시 `environment_check`로 사용 가능한 공급자(Ollama, Gemini CLI, Codex CLI)를 자동 감지합니다.
 
 ### 사전 요구사항
 
@@ -30,6 +30,9 @@ Claude Code에서 실행:
 | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `npm install -g @google/gemini-cli` | 클라우드 |
 | [Codex CLI](https://github.com/openai/codex) | `npm install -g @openai/codex` | 클라우드 |
 
+선택 사항이지만 권장:
+- **tmux** — 자율 실행 중 CLI 워커 패인을 시각적으로 확인 가능
+
 ---
 
 ## 철학
@@ -44,16 +47,34 @@ Claude Code에서 실행:
 | `/agestra idea [주제]` | 유사 프로젝트 비교를 통한 개선점 발굴 |
 | `/agestra design [주제]` | 구현 전 아키텍처 및 설계 트레이드오프 탐색 |
 
-각 커맨드는 선택지를 제시합니다: **Claude만**, **비교** (여러 AI 나란히), **토론** (구조화된 멀티AI 논의), **기타** (사용자 지정).
+각 커맨드는 선택지를 제시합니다:
+
+| 모드 | 설명 |
+|------|------|
+| **Claude only** | 플러그인 전문 에이전트가 단독 작업 |
+| **각자 독립** | 각 AI가 독립 작업 후 진행자가 취합하여 통합 문서 작성 |
+| **끝장토론** | 각자 독립 + 문서를 돌아가며 분석/피드백, 모든 AI가 동의할 때까지 |
 
 ## 에이전트
 
 | 에이전트 | 모델 | 역할 |
 |----------|------|------|
-| `reviewer` | Opus | 엄격한 품질 검증 — 보안, 고아 시스템, 스펙 이탈, 테스트 공백 |
-| `designer` | Opus | 아키텍처 탐색 — 소크라테스식 질문, 트레이드오프 분석 |
-| `ideator` | Sonnet | 개선점 발굴 — 웹 리서치, 경쟁 분석 |
-| `moderator` | Sonnet | 토론 진행 — 중립, 턴 관리, 합의 판정 |
+| `agestra-team-lead` | Sonnet | 풀 오케스트레이터 — 환경 체크, 품질 기반 공급자 라우팅, 작업 모드 선택, CLI 워커 감독, QA 루프 |
+| `agestra-reviewer` | Opus | 엄격한 품질 검증 — 보안, 고아 시스템, 스펙 이탈, 테스트 공백 |
+| `agestra-designer` | Opus | 아키텍처 탐색 — 소크라테스식 질문, 트레이드오프 분석 |
+| `agestra-ideator` | Sonnet | 개선점 발굴 — 웹 리서치, 경쟁 분석 |
+| `agestra-moderator` | Sonnet | 다목적 진행자 — 합의 검출 토론, 독립 취합, 문서 라운드 리뷰, 충돌 해결 |
+| `agestra-qa` | Opus | QA 검증 — 설계 준수, PASS/FAIL 판정 |
+
+## 스킬
+
+| 스킬 | 설명 |
+|------|------|
+| `provider-guide` | 공급자 라우팅, 모드 참조, 오케스트레이션 파이프라인 |
+| `worker-manage` | CLI 워커 목록, 상태 확인, 결과 수집, 중지 |
+| `cancel` | 워커, 토론, 체인, 작업의 정상 종료 |
+| `build-fix` | 빌드/타입체크/린트 에러 자동 진단 및 수정 |
+| `trace` | 에이전트 실행 타임라인 및 흐름 다이어그램 조회 |
 
 ---
 
@@ -63,14 +84,14 @@ Turborepo 모노레포, 8개 패키지:
 
 | 패키지 | 설명 |
 |--------|------|
-| `@agestra/core` | `AIProvider` 인터페이스, 레지스트리, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐 |
+| `@agestra/core` | `AIProvider` 인터페이스, 난이도 기반 라우팅 레지스트리, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐, 시크릿 스캐너, 워크트리 관리자, 태스크 매니페스트, CLI 워커 관리자 |
 | `@agestra/provider-ollama` | Ollama HTTP 어댑터 (모델 자동 감지) |
 | `@agestra/provider-gemini` | Google Gemini CLI 어댑터 |
 | `@agestra/provider-codex` | OpenAI Codex CLI 어댑터 |
-| `@agestra/agents` | 토론 엔진, 작업 분배기, 교차 검증기, 작업 체인, 자동 QA, 파일 변경 추적기, 세션 관리자 |
+| `@agestra/agents` | 합의 검출 토론 엔진, 턴 품질 평가기, 작업 분배기, 교차 검증기, 작업 체인, 자동 QA, 파일 변경 추적기, 세션 관리자 |
 | `@agestra/workspace` | 코드 리뷰 워크플로우용 문서 관리자 |
 | `@agestra/memory` | GraphRAG — FTS5 + 벡터 + 지식 그래프 하이브리드 검색, 실패 추적 |
-| `@agestra/mcp-server` | MCP 프로토콜 레이어, 39개 도구, 디스패치 |
+| `@agestra/mcp-server` | MCP 프로토콜 레이어, 49개 도구, 디스패치 |
 
 ### 설계 원칙
 
@@ -80,10 +101,19 @@ Turborepo 모노레포, 8개 패키지:
 - **모듈형 디스패치** — 각 도구 카테고리가 `getTools()` + `handleTool()`을 내보내는 독립 모듈. 서버가 동적으로 수집·디스패치.
 - **원자적 쓰기** — 모든 파일 연산이 임시 파일 → rename 방식. 크래시 시 손상 방지.
 - **실패 추적** — 실패한 접근법이 GraphRAG에 자동 기록, 이후 프롬프트에 주입.
+- **사전 보안 검증** — CLI 워커 스폰 시 시크릿 스캔 + 배열 기반 프로세스 인자로 인젝션 방지.
+
+### 작업 모드
+
+**텍스트 작업** (리뷰, 설계, 아이디어): Claude only → 각자 독립 → 끝장토론
+
+**구현 작업** (team-lead 오케스트레이션):
+- **Claude만으로** — Claude가 프로젝트/전역 에이전트를 활용해 직접 구현.
+- **다른 AI도 함께** — CLI 워커(Codex/Gemini)가 격리된 git worktree에서 자율 코딩, Ollama가 단순 작업 처리, Claude가 감독 및 병합.
 
 ---
 
-## 도구 (39개)
+## 도구 (49개)
 
 ### AI 채팅 (3개)
 
@@ -93,7 +123,7 @@ Turborepo 모노레포, 8개 패키지:
 | `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 |
 | `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 |
 
-### 에이전트 오케스트레이션 (16개)
+### 에이전트 오케스트레이션 (20개)
 
 | 도구 | 설명 |
 |------|------|
@@ -102,6 +132,7 @@ Turborepo 모노레포, 8개 패키지:
 | `agent_debate_create` | 턴 기반 토론 세션 생성 (토론 ID 반환) |
 | `agent_debate_turn` | 공급자 1턴 실행; `provider: "claude"`로 Claude 독립 참여 지원 |
 | `agent_debate_conclude` | 토론 종료 및 최종 트랜스크립트 생성 |
+| `agent_debate_moderate` | 완전 자동화 토론 — 세션 생성, Specialist 에이전트 참여 라운드 실행, 합의 검출, 요약만 반환 |
 | `agent_debate_review` | 문서를 여러 공급자에게 독립적으로 리뷰 요청 |
 | `agent_assign_task` | 특정 공급자에게 작업 위임 |
 | `agent_task_status` | 작업 완료 상태 및 결과 확인 |
@@ -109,12 +140,30 @@ Turborepo 모노레포, 8개 패키지:
 | `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) |
 | `agent_task_chain_create` | 의존성과 체크포인트가 있는 다단계 작업 체인 생성 |
 | `agent_task_chain_step` | 체인의 다음 (또는 지정) 단계 실행 |
+| `agent_task_chain_step_async` | 단계를 비동기로 실행 (논블로킹) |
+| `agent_task_chain_await` | 비동기 단계 완료 대기 |
 | `agent_task_chain_status` | 체인 진행 상태 및 단계 결과 확인 |
 | `agent_changes_review` | 격리된 작업의 파일 변경 리뷰 |
 | `agent_changes_accept` | 격리된 작업의 변경 수락 및 병합 |
 | `agent_changes_reject` | 변경 거부 및 격리 워크트리 정리 |
+| `session_list` | 에이전트 세션 목록 조회 (유형/상태 필터링) |
+
+### CLI 워커 (4개)
+
+| 도구 | 설명 |
+|------|------|
+| `cli_worker_spawn` | CLI AI(Codex/Gemini)를 자율 모드로 스폰 — git worktree 격리 + 사전 보안 검증 |
+| `cli_worker_status` | 워커 FSM 상태, 하트비트, 출력 미리보기 확인 |
+| `cli_worker_collect` | 완료된 워커 결과 수집 (git diff, 출력, 종료 코드) |
+| `cli_worker_stop` | 실행 중인 워커 중지 (SIGTERM → SIGKILL) + 워크트리 정리 |
+
+### 환경 (1개)
+
+| 도구 | 설명 |
+|------|------|
+| `environment_check` | CLI 도구, Ollama 모델 티어, tmux, git worktree 지원 여부, 사용 가능 모드 탐지 |
 
-### 워크스페이스 (5개)
+### 워크스페이스 (6개)
 
 | 도구 | 설명 |
 |------|------|
@@ -123,6 +172,7 @@ Turborepo 모노레포, 8개 패키지:
 | `workspace_review_status` | 리뷰 완료 상태 확인 |
 | `workspace_add_comment` | 리뷰에 코멘트 추가 |
 | `workspace_read` | 리뷰 내용 읽기 |
+| `workspace_list` | 워크스페이스의 모든 리뷰 문서 목록 조회 |
 
 ### 공급자 관리 (2개)
 
@@ -135,7 +185,7 @@ Turborepo 모노레포, 8개 패키지:
 
 | 도구 | 설명 |
 |------|------|
-| `ollama_models` | 설치된 모델 및 크기 목록 |
+| `ollama_models` | 설치된 모델 및 크기, 티어 분류 목록 |
 | `ollama_pull` | 모델 다운로드 |
 
 ### 메모리 (6개)
@@ -161,7 +211,7 @@ Turborepo 모노레포, 8개 패키지:
 | 도구 | 설명 |
 |------|------|
 | `trace_query` | 조건별 추적 레코드 조회 (공급자, 작업, 기간) |
-| `trace_summary` | 공급자별·작업별 품질 및 성능 통계 |
+| `trace_summary` | 공급자별 품질 통계, 성능 지표, 난이도 자격 확인 |
 | `trace_visualize` | 추적된 작업 흐름의 Mermaid 다이어그램 생성 |
 
 ---
@@ -190,6 +240,8 @@ Agestra는 시작 시 공급자를 자동 감지합니다. 수동 제어가 필
 | `.agestra/workspace/` | 코드 리뷰 문서 |
 | `.agestra/memory.db` | GraphRAG SQLite 데이터베이스 |
 | `.agestra/.jobs/` | 백그라운드 작업 큐 |
+| `.agestra/.workers/` | CLI 워커 상태, 매니페스트, 출력 로그 |
+| `.agestra/worktrees/` | CLI 워커 격리 실행용 git worktree |
 | `.agestra/traces/` | 공급자 추적 JSONL (30일 후 자동 정리) |
 
 ---
@@ -218,14 +270,18 @@ agestra/
 │   ├── idea.md              # /agestra idea — 개선점 발굴
 │   └── design.md            # /agestra design — 아키텍처 탐색
 ├── agents/
-│   ├── reviewer.md          # 엄격한 품질 검증자 (Opus)
-│   ├── designer.md          # 아키텍처 탐색자 (Opus)
-│   ├── ideator.md           # 개선점 발굴자 (Sonnet)
-│   ├── moderator.md         # 토론 진행자 (Sonnet)
-│   ├── qa.md                # QA 검증자 (프로젝트 내부)
-│   └── team-lead.md         # 작업 오케스트레이터 (프로젝트 내부)
+│   ├── 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    # 공급자 사용 가이드라인 (skill)
+│   ├── provider-guide.md    # 공급자 라우팅 및 모드 참조
+│   ├── worker-manage.md     # CLI 워커 관리
+│   ├── cancel.md            # 정상 작업 취소
+│   ├── build-fix.md         # 빌드 에러 자동 수정
+│   └── trace.md             # 실행 타임라인 조회
 ├── hooks/
 │   └── user-prompt-submit.md  # 도구 추천 hook
 ├── dist/
@@ -233,14 +289,14 @@ agestra/
 ├── scripts/
 │   └── bundle.mjs           # esbuild 번들 스크립트
 ├── packages/
-│   ├── core/                # AIProvider 인터페이스, 레지스트리
+│   ├── core/                # AIProvider 인터페이스, 레지스트리, 보안, 워커
 │   ├── provider-ollama/     # Ollama HTTP 어댑터
 │   ├── provider-gemini/     # Gemini CLI 어댑터
 │   ├── provider-codex/      # Codex CLI 어댑터
 │   ├── agents/              # 토론 엔진, 분배기, 교차 검증기
 │   ├── workspace/           # 코드 리뷰 문서 관리자
 │   ├── memory/              # GraphRAG: 하이브리드 검색, 실패 추적
-│   └── mcp-server/          # MCP 서버, 39개 도구, 디스패치
+│   └── mcp-server/          # MCP 서버, 49개 도구, 디스패치
 ├── package.json             # 워크스페이스 루트
 └── turbo.json               # Turborepo 파이프라인
 ```

package/README.md

@@ -7,7 +7,7 @@
 
 [English](README.md) | [한국어](README.ko.md)
 
-Agestra connects Ollama (local), Gemini CLI, and Codex CLI to Claude Code as pluggable providers, enabling multi-agent debates, parallel task dispatch, cross-validation, and a persistent GraphRAG memory system — all through 39 MCP tools.
+Agestra connects Ollama (local), Gemini CLI, and Codex CLI to Claude Code as pluggable providers, enabling multi-agent orchestration with independent aggregation, consensus debates, autonomous CLI workers, parallel task dispatch, cross-validation, quality-based provider routing, and a persistent GraphRAG memory system — all through 49 MCP tools.
 
 ## Quick Start
 
@@ -18,7 +18,7 @@ In Claude Code, run:
 /plugin install agestra@agestra
 ```
 
-That's it. Agestra auto-detects available providers (Ollama, Gemini CLI, Codex CLI) on first use.
+That's it. Agestra auto-detects available providers (Ollama, Gemini CLI, Codex CLI) on first use via `environment_check`.
 
 ### Prerequisites
 
@@ -30,6 +30,9 @@ At least one AI provider must be installed:
 | [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 |
 
+Optional but recommended:
+- **tmux** — enables visible CLI worker panes during autonomous execution
+
 ---
 
 ## Philosophy
@@ -44,16 +47,34 @@ At least one AI provider must be installed:
 | `/agestra idea [topic]` | Discover improvements by comparing with similar projects |
 | `/agestra design [subject]` | Explore architecture and design trade-offs before implementation |
 
-Each command presents a choice: **Claude only**, **Compare** (multiple AIs side-by-side), **Debate** (structured multi-AI discussion), or **Other** (user-specified).
+Each command presents a choice:
+
+| Mode | Description |
+|------|-------------|
+| **Claude only** | Plugin specialist agent works alone |
+| **각자 독립** (Independent) | Each AI works independently, moderator aggregates into unified document |
+| **끝장토론** (Debate) | Independent work + document review rounds until all AIs agree |
 
 ## Agents
 
 | Agent | Model | Role |
 |-------|-------|------|
-| `reviewer` | Opus | Strict quality verifier — security, orphans, spec drift, test gaps |
-| `designer` | Opus | Architecture explorer — Socratic questioning, trade-off analysis |
-| `ideator` | Sonnet | Improvement discoverer — web research, competitive analysis |
-| `moderator` | Sonnet | Debate facilitator — neutral, manages turns, judges consensus |
+| `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop |
+| `agestra-reviewer` | Opus | Strict quality verifier — security, orphans, spec drift, test gaps |
+| `agestra-designer` | Opus | Architecture explorer — Socratic questioning, trade-off analysis |
+| `agestra-ideator` | Sonnet | Improvement discoverer — web research, competitive analysis |
+| `agestra-moderator` | Sonnet | Multi-mode facilitator — debate with consensus detection, independent aggregation, document review, conflict resolution |
+| `agestra-qa` | Opus | QA verifier — design compliance, PASS/FAIL judgment |
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `provider-guide` | Provider routing, mode reference, orchestration pipeline |
+| `worker-manage` | List, check, collect, and stop CLI workers |
+| `cancel` | Graceful stop for workers, debates, chains, tasks |
+| `build-fix` | Auto-diagnose and fix build/typecheck/lint errors |
+| `trace` | View agent execution timeline and flow diagrams |
 
 ---
 
@@ -63,14 +84,14 @@ Turborepo monorepo with 8 packages:
 
 | Package | Description |
 |---------|-------------|
-| `@agestra/core` | `AIProvider` interface, registry, config loader, CLI runner, atomic writes, job queue |
+| `@agestra/core` | `AIProvider` interface, registry with difficulty-based routing, config loader, CLI runner, atomic writes, job queue, secret scanner, worktree manager, task manifest, CLI worker manager |
 | `@agestra/provider-ollama` | Ollama HTTP adapter with model detection |
 | `@agestra/provider-gemini` | Google Gemini CLI adapter |
 | `@agestra/provider-codex` | OpenAI Codex CLI adapter |
-| `@agestra/agents` | Debate engine, task dispatcher, cross-validator, task chain, auto-QA, file change tracker, session manager |
+| `@agestra/agents` | Debate engine with consensus detection, turn quality evaluator, task dispatcher, cross-validator, task chain, auto-QA, file change tracker, session manager |
 | `@agestra/workspace` | Document manager for code review workflows |
 | `@agestra/memory` | GraphRAG — FTS5 + vector + knowledge graph hybrid search, dead-end tracking |
-| `@agestra/mcp-server` | MCP protocol layer, 39 tools, dispatch |
+| `@agestra/mcp-server` | MCP protocol layer, 49 tools, dispatch |
 
 ### Design Principles
 
@@ -80,10 +101,19 @@ Turborepo monorepo with 8 packages:
 - **Modular dispatch** — Each tool category is an independent module with `getTools()` + `handleTool()`. The server collects and dispatches dynamically.
 - **Atomic writes** — All file operations use write-to-temp-then-rename to prevent corruption.
 - **Dead-end tracking** — Failed approaches are recorded in GraphRAG and injected into future prompts.
+- **Preflight security** — CLI worker spawning includes secret scanning and array-based process args to prevent injection.
+
+### Work Modes
+
+**Text work** (review, design, idea): Claude only → 각자 독립 → 끝장토론
+
+**Implementation work** (team-lead orchestration):
+- **Claude만으로** — Claude implements directly with project/global agents.
+- **다른 AI도 함께** — CLI workers (Codex/Gemini) do autonomous coding in isolated git worktrees, Ollama handles simple tasks, Claude supervises and merges.
 
 ---
 
-## Tools (39)
+## Tools (49)
 
 ### AI Chat (3)
 
@@ -93,7 +123,7 @@ Turborepo monorepo with 8 packages:
 | `ai_analyze_files` | Read files from disk and send contents with a question to a provider |
 | `ai_compare` | Send the same prompt to multiple providers, compare responses |
 
-### Agent Orchestration (16)
+### Agent Orchestration (20)
 
 | Tool | Description |
 |------|-------------|
@@ -102,6 +132,7 @@ Turborepo monorepo with 8 packages:
 | `agent_debate_create` | Create a turn-based debate session (returns debate ID) |
 | `agent_debate_turn` | Execute one provider's turn; supports `provider: "claude"` for Claude's independent participation |
 | `agent_debate_conclude` | End a debate and generate final transcript |
+| `agent_debate_moderate` | Run a fully automated debate — creates session, runs rounds with specialist agents, detects consensus, returns summary only |
 | `agent_debate_review` | Send a document to multiple providers for independent review |
 | `agent_assign_task` | Delegate a task to a specific provider |
 | `agent_task_status` | Check task completion and result |
@@ -109,12 +140,30 @@ Turborepo monorepo with 8 packages:
 | `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) |
 | `agent_task_chain_create` | Create a multi-step task chain with dependencies and checkpoints |
 | `agent_task_chain_step` | Execute the next (or specified) step in a chain |
+| `agent_task_chain_step_async` | Execute a step asynchronously (non-blocking) |
+| `agent_task_chain_await` | Wait for an async step to complete |
 | `agent_task_chain_status` | Check chain progress and step results |
 | `agent_changes_review` | Review file changes from an isolated task |
 | `agent_changes_accept` | Accept and merge changes from an isolated task |
 | `agent_changes_reject` | Reject changes and clean up the isolated worktree |
+| `session_list` | List all agent sessions with optional type/status filtering |
+
+### CLI Workers (4)
+
+| Tool | Description |
+|------|-------------|
+| `cli_worker_spawn` | Spawn a CLI AI (Codex/Gemini) in autonomous mode with git worktree isolation and preflight security |
+| `cli_worker_status` | Check worker FSM state, heartbeat, and output tail |
+| `cli_worker_collect` | Collect completed worker results (git diff, output, exit code) |
+| `cli_worker_stop` | Stop a running worker (SIGTERM → SIGKILL) and clean up worktree |
+
+### Environment (1)
+
+| Tool | Description |
+|------|-------------|
+| `environment_check` | Detect CLI tools, Ollama models with tiers, tmux, git worktree support, available modes |
 
-### Workspace (5)
+### Workspace (6)
 
 | Tool | Description |
 |------|-------------|
@@ -123,6 +172,7 @@ Turborepo monorepo with 8 packages:
 | `workspace_review_status` | Check review completion status |
 | `workspace_add_comment` | Add a comment to a review |
 | `workspace_read` | Read review contents |
+| `workspace_list` | List all review documents in the workspace |
 
 ### Provider Management (2)
 
@@ -135,7 +185,7 @@ Turborepo monorepo with 8 packages:
 
 | Tool | Description |
 |------|-------------|
-| `ollama_models` | List installed models with sizes |
+| `ollama_models` | List installed models with sizes and tier classification |
 | `ollama_pull` | Download a model |
 
 ### Memory (6)
@@ -161,7 +211,7 @@ Turborepo monorepo with 8 packages:
 | Tool | Description |
 |------|-------------|
 | `trace_query` | Query trace records with filtering (provider, task, time range) |
-| `trace_summary` | Get quality and performance stats per provider and task type |
+| `trace_summary` | Get quality stats, performance metrics, and difficulty qualification per provider |
 | `trace_visualize` | Generate a Mermaid diagram of a traced operation's flow |
 
 ---
@@ -190,6 +240,8 @@ Stored under `.agestra/` (gitignored):
 | `.agestra/workspace/` | Code review documents |
 | `.agestra/memory.db` | GraphRAG SQLite database |
 | `.agestra/.jobs/` | Background job queue |
+| `.agestra/.workers/` | CLI worker state, manifests, and output logs |
+| `.agestra/worktrees/` | Git worktrees for isolated CLI worker execution |
 | `.agestra/traces/` | Provider trace JSONL (auto-pruned after 30 days) |
 
 ---
@@ -218,14 +270,18 @@ agestra/
 │   ├── idea.md              # /agestra idea — improvement discovery
 │   └── design.md            # /agestra design — architecture exploration
 ├── agents/
-│   ├── reviewer.md          # Strict quality verifier (Opus)
-│   ├── designer.md          # Architecture explorer (Opus)
-│   ├── ideator.md           # Improvement discoverer (Sonnet)
-│   ├── moderator.md         # Debate facilitator (Sonnet)
-│   ├── qa.md                # QA verifier (project-internal)
-│   └── team-lead.md         # Task orchestrator (project-internal)
+│   ├── agestra-reviewer.md  # Strict quality verifier (Opus)
+│   ├── agestra-designer.md  # Architecture explorer (Opus)
+│   ├── agestra-ideator.md   # Improvement discoverer (Sonnet)
+│   ├── agestra-moderator.md # Multi-mode facilitator (Sonnet)
+│   ├── agestra-qa.md        # QA verifier (Opus, no code writes)
+│   └── agestra-team-lead.md # Full orchestrator (Sonnet, no code writes)
 ├── skills/
-│   └── provider-guide.md    # Provider usage guidelines (skill)
+│   ├── provider-guide.md    # Provider routing and mode reference
+│   ├── worker-manage.md     # CLI worker management
+│   ├── cancel.md            # Graceful operation cancellation
+│   ├── build-fix.md         # Build error auto-repair
+│   └── trace.md             # Execution timeline viewer
 ├── hooks/
 │   └── user-prompt-submit.md  # Tool recommendation hook
 ├── dist/
@@ -233,14 +289,14 @@ agestra/
 ├── scripts/
 │   └── bundle.mjs           # esbuild bundle script
 ├── packages/
-│   ├── core/                # AIProvider interface, registry
+│   ├── core/                # AIProvider interface, registry, security, workers
 │   ├── provider-ollama/     # Ollama HTTP adapter
 │   ├── provider-gemini/     # Gemini CLI adapter
 │   ├── provider-codex/      # Codex CLI adapter
 │   ├── agents/              # Debate engine, dispatcher, cross-validator
 │   ├── workspace/           # Code review document manager
 │   ├── memory/              # GraphRAG: hybrid search, dead-end tracking
-│   └── mcp-server/          # MCP server, 39 tools, dispatch
+│   └── mcp-server/          # MCP server, 49 tools, dispatch
 ├── package.json             # Workspace root
 └── turbo.json               # Turborepo pipeline
 ```

package/agents/agestra-designer.md

@@ -0,0 +1,122 @@
+---
+name: agestra-designer
+description: |
+  Pre-implementation design explorer using Socratic questioning. Explores architecture,
+  discusses design trade-offs, and establishes direction before coding.
+  Triggers: "design this", "how should I architect", "explore approaches", "design trade-offs",
+  "설계", "아키텍처", "구조 잡아줘", "어떻게 만들지", "방향 잡아줘",
+  "設計", "アーキテクチャ", "架构", "设计"
+model: claude-opus-4-6
+---
+
+<Role>
+You are a pre-implementation design explorer. Your job is to help the user find the right architecture before any code is written. You use Socratic questioning to understand intent, explore the codebase for existing patterns, propose multiple approaches with trade-offs, and produce a design document.
+</Role>
+
+<Scope>
+You design features and systems **for the current project** (the codebase you're running in). If the user's request is outside this project's scope — a new product idea, a business question, or something unrelated to this codebase — say so directly:
+
+> "This is outside the current project's scope. I design features within this codebase. If you're looking for project ideas, try `/agestra idea` instead."
+
+Do not attempt to design something that cannot be implemented in the current codebase.
+</Scope>
+
+<Workflow>
+Follow these phases in order. Do not skip phases.
+
+### Phase 1: Understand (Clarity Gate)
+
+Before asking questions, check if the request is already clear. If it includes specific file paths, function names, or concrete acceptance criteria, score immediately — skip the interview if ambiguity is already low.
+
+**Clarity Dimensions:**
+
+| Dimension | Weight (greenfield) | Weight (brownfield) |
+|-----------|-------------------|-------------------|
+| Goal | 40% | 35% |
+| Constraints | 30% | 25% |
+| Success Criteria | 30% | 25% |
+| Context | N/A | 15% |
+
+Greenfield: no relevant source code exists for the feature.
+Brownfield: modifying or extending existing code.
+
+**After each user answer:**
+1. Score all dimensions 0.0–1.0
+2. Calculate: `ambiguity = 1 - weighted_sum`
+3. Display progress to the user:
+   ```
+   Round {n} | Ambiguity: {score}% | Targeting: {weakest dimension}
+   ```
+4. If ambiguity <= 20% → proceed to Phase 2
+5. If ambiguity > 20% → ask the next question targeting the WEAKEST dimension
+
+**Question targeting:** Always target the dimension with the lowest score. Ask ONE question at a time. Expose assumptions, not feature lists.
+
+| Dimension | Question Style |
+|-----------|---------------|
+| Goal | "What exactly happens when...?" / "What specific action does a user take first?" |
+| Constraints | "What are the boundaries?" / "Should this work offline?" |
+| Success Criteria | "How do we know it works?" / "What would make you say 'yes, that's it'?" |
+| Context (brownfield) | "How does this fit with existing...?" / "Extend or replace?" |
+
+**Challenge modes** (each used once, then return to normal):
+- Round 4+: **Contrarian** — "What if the opposite were true? What if this constraint doesn't actually exist?"
+- Round 6+: **Simplifier** — "What's the simplest version that would still be valuable?"
+- Round 8+: **Ontologist** (if ambiguity still > 30%) — "What IS this, really? One sentence."
+
+**Soft limits:**
+- Round 3+: allow early exit if user says "enough" — show ambiguity warning
+- Round 10: soft warning — "We're at 10 rounds. Current ambiguity: {score}%. Continue or proceed?"
+- Round 20: hard cap — proceed with current clarity, note the risk
+
+### Phase 2: Explore
+Search the codebase for relevant existing patterns:
+- Use Glob to find related files by name
+- Use Grep to find similar implementations
+- Use Read to understand existing architecture
+- Note conventions: naming, file organization, patterns used
+
+### Phase 3: Propose
+Present 2-3 distinct approaches. For each:
+- **Approach name** — one-line summary
+- **How it works** — architecture overview
+- **Fits with** — which existing patterns it aligns with
+- **Trade-offs** — pros and cons
+- **Effort** — relative complexity (low/medium/high)
+
+### Phase 4: Refine
+Based on user feedback:
+- Deep-dive into the selected approach
+- Address concerns raised
+- Detail component boundaries and data flow
+- Identify risks and mitigation
+
+### Phase 5: Document
+Write a design document to `docs/plans/` with this structure:
+
+```markdown
+# [Feature/System Name] Design
+
+## Problem
+## Approach
+## Architecture
+## Components
+## Data Flow
+## Trade-offs & Decisions
+## Open Questions
+## Implementation Steps
+```
+</Workflow>
+
+<Constraints>
+- Ask one question at a time. Do not dump multiple questions.
+- Present approaches before solutions. Let the user choose direction.
+- Always explore the codebase before proposing — do not design in a vacuum.
+- Document all decisions made during the conversation in the final design document.
+- Do not write implementation code. Design documents only.
+- Communicate in the user's language.
+</Constraints>
+
+<Output_Format>
+Your final deliverable is a design document in `docs/plans/` following the template above. The document should be self-contained — someone reading it without conversation context should understand the design fully.
+</Output_Format>