agestra 4.10.5 → 4.12.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "agestra",
       "source": "./",
       "description": "Orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
-      "version": "4.10.5",
+      "version": "4.12.0",
       "author": {
         "name": "mua-vtuber"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agestra",
-  "version": "4.10.5",
+  "version": "4.12.0",
   "description": "Claude Code plugin — orchestrate Ollama, Gemini, and Codex for multi-AI debates, code review, and cross-validation",
   "mcpServers": {
     "agestra": {

package/.gemini/commands/agestra/implement.toml

@@ -9,8 +9,9 @@ Use the shared workflow spec below as the source of truth and adapt it to the cu
 @{commands/implement.md}
 
 Gemini-specific rules:
-- Start with `environment_check` and `provider_list`.
+- Start with `setup_status`, then `environment_check` and `provider_list`.
 - Prefer Agestra MCP tools and worker orchestration over ad-hoc shell-heavy implementation plans.
-- Translate Claude-specific wording into leader-host wording when Gemini is the active host.
+- Treat "Leader-host only" as the Gemini-led local path when Gemini is the active host.
+- Use the shared `agestra-implementer` role semantics for host-local code edits.
 - Keep the final answer in the user's language.
 """

package/AGENTS.md

@@ -13,7 +13,7 @@ This repository includes a Codex-friendly host wrapper for Agestra.
 - Treat `commands/*.md` as the source of truth for Agestra workflows.
 - When the user asks for review, design, idea, or implementation help, start with `environment_check` and `provider_list`.
 - Prefer Agestra MCP tools over ad-hoc multi-provider prompting.
-- If a workflow mentions "Claude only", interpret that as the current leader-host-only path when Claude is not the active host.
+- If any legacy workflow text mentions "Claude only", interpret that as the current leader-host-only path when Claude is not the active host.
 
 ## Workflow Mapping
 

package/GEMINI.md

@@ -24,7 +24,7 @@ Each command delegates to the shared workflow specs in `commands/*.md`.
 - Start orchestration requests with `environment_check` and `provider_list`.
 - Prefer Agestra MCP tools instead of rebuilding workflows in free-form prompts.
 - Treat `commands/*.md` and `agents/*.md` as the canonical workflow and role assets.
-- If a shared workflow mentions "Claude only", translate that to the current leader-host-only path when Gemini is the active host.
+- If any legacy shared workflow text mentions "Claude only", translate that to the current leader-host-only path when Gemini is the active host.
 
 ## Core MCP Tools
 

package/README.ja.md

@@ -84,7 +84,7 @@ Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md) と、[`.gemini/com
 | `/agestra setup` | 初期 AI プロバイダー選択とセットアップ |
 | `/agestra implement [task]` | Claude only または Multi-AI モードで実装を進める |
 
-外部プロバイダーが利用可能な場合、テキストコマンド（review、design、idea）は直接ディベートモードに入り、マルチ AI クロスバリデーションを行います。プロバイダーが検出されない場合、Claude が自動的に単独で作業します。
+外部プロバイダーが利用可能な場合、テキストコマンド（review、design、idea）は直接徹底討論モードに入り、マルチ AI クロスバリデーションを行います。プロバイダーが検出されない場合、Claude が自動的に単独で作業します。
 
 ## エージェント
 
@@ -106,8 +106,11 @@ Gemini ではリポジトリ直下の [GEMINI.md](GEMINI.md) と、[`.gemini/com
 | `cancel` | ワーカー、ディベート、チェーン、タスクの安全な停止 |
 | `build-fix` | build/typecheck/lint エラーの自動診断と修正 |
 | `trace` | エージェント実行タイムラインとフローダイアグラムの表示 |
+| `setup` | 初期プロバイダー選択と `providers.config.json` 書き込み |
 | `design` | Multi-AI モード選択を含む設計探索ワークフロー |
 | `idea` | Multi-AI モード選択を含む改善案発見ワークフロー |
+| `review` | Multi-AI モード選択を含むコード品質・セキュリティ・ハードコーディングレビューワークフロー |
+| `leader` | マルチAI/プロバイダーオーケストレーションのエントリーポイント — 明示的なプロバイダー、ディベート、合意形成、相互検証シグナルを検知し、ドメイン分類後 `agestra-team-lead` へ委譲 |
 
 ---
 
@@ -137,7 +140,7 @@ Turborepo モノレポで、9 パッケージ構成です:
 
 ### 作業モード
 
-**Text work**（レビュー、設計、アイデア）: プロバイダーあり → ディベートモード; なし → Claude only
+**Text work**（レビュー、設計、アイデア）: プロバイダーあり → 徹底討論モード; なし → Claude only
 
 **Implementation work**（team-lead orchestration）:
 - **Claude만으로** — Claude がプロジェクト/グローバルエージェントを使って直接実装します。
@@ -314,7 +317,12 @@ agestra/
 │   ├── worker-manage.md     # CLI ワーカー管理
 │   ├── cancel.md            # 安全な操作キャンセル
 │   ├── build-fix.md         # ビルドエラー自動修復
-│   └── trace.md             # 実行タイムラインビューア
+│   ├── trace.md             # 実行タイムラインビューア
+│   ├── setup.md             # 初期プロバイダー選択
+│   ├── design.md            # 設計探索ワークフロー
+│   ├── idea.md              # 改善案発見ワークフロー
+│   ├── review.md            # コード品質レビューワークフロー
+│   └── leader.md            # マルチAIオーケストレーションルーター
 ├── hooks/
 │   └── user-prompt-submit.md  # ツール推奨フック
 ├── dist/

package/README.ko.md

@@ -70,6 +70,7 @@ Gemini는 저장소 루트의 [GEMINI.md](GEMINI.md)와 [`.gemini/commands/agest
 
 설치 후 Gemini에서 사용할 수 있는 명령:
 
+- `/agestra:setup`
 - `/agestra:review`
 - `/agestra:design`
 - `/agestra:idea`
@@ -147,8 +148,11 @@ winget install BurntSushi.ripgrep.MSVC
 | `cancel` | 워커, 토론, 체인, 작업의 정상 종료 |
 | `build-fix` | 빌드/타입체크/린트 에러 자동 진단 및 수정 |
 | `trace` | 에이전트 실행 타임라인 및 흐름 다이어그램 조회 |
+| `setup` | 초기 공급자 선택 및 `providers.config.json` 작성 |
 | `design` | 멀티 AI 모드 선택이 포함된 아키텍처 탐색 워크플로우 |
 | `idea` | 멀티 AI 모드 선택이 포함된 개선점 발굴 워크플로우 |
+| `review` | 멀티 AI 모드 선택이 포함된 코드 품질·보안·하드코딩 리뷰 워크플로우 |
+| `leader` | 멀티 AI/프로바이더 오케스트레이션 진입점 — 명시적인 프로바이더, 토론, 합의, 교차 검증 신호를 잡아 도메인을 분류한 뒤 `agestra-team-lead`에 위임 |
 
 ---
 
@@ -283,7 +287,7 @@ Turborepo 모노레포, 9개 패키지:
 
 ### providers.config.json
 
-`/agestra setup`이 생성합니다. 단일 플러그인 범위 경로에 저장됩니다 (해석 우선순위: `AGESTRA_CONFIG_PATH` 환경변수 → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`). 프로젝트 저장소에 두지 않으며 gitignore에도 등록되어 있습니다.
+`/agestra setup`이 생성합니다. 기본 저장 위치는 호스트 공용 `~/.agestra/providers.config.json`입니다. 해석 우선순위는 `AGESTRA_CONFIG_PATH` 환경변수 → 기존 `~/.agestra/providers.config.json` → 기존 레거시 `$CLAUDE_PLUGIN_ROOT/providers.config.json` → 새 파일용 `~/.agestra/providers.config.json`입니다. 프로젝트 저장소에 두지 않으며 gitignore에도 등록되어 있습니다.
 
 | 필드 | 설명 |
 |------|------|
@@ -334,6 +338,7 @@ agestra/
 ├── .gemini/
 │   └── commands/
 │       └── agestra/
+│           ├── setup.toml   # Gemini CLI의 /agestra:setup
 │           ├── review.toml  # Gemini CLI의 /agestra:review
 │           ├── design.toml  # Gemini CLI의 /agestra:design
 │           ├── idea.toml    # Gemini CLI의 /agestra:idea
@@ -355,7 +360,12 @@ agestra/
 │   ├── worker-manage.md     # CLI 워커 관리
 │   ├── cancel.md            # 정상 작업 취소
 │   ├── build-fix.md         # 빌드 에러 자동 수정
-│   └── trace.md             # 실행 타임라인 조회
+│   ├── trace.md             # 실행 타임라인 조회
+│   ├── setup.md             # 초기 공급자 선택
+│   ├── design.md            # 아키텍처 탐색 워크플로우
+│   ├── idea.md              # 개선점 발굴 워크플로우
+│   ├── review.md            # 코드 품질 리뷰 워크플로우
+│   └── leader.md            # 멀티 AI 오케스트레이션 라우터
 ├── hooks/
 │   └── user-prompt-submit.md  # 도구 추천 hook
 ├── dist/

package/README.md

@@ -70,6 +70,7 @@ Gemini uses the repository-level [GEMINI.md](GEMINI.md) context file plus projec
 
 Available Gemini commands after setup:
 
+- `/agestra:setup`
 - `/agestra:review`
 - `/agestra:design`
 - `/agestra:idea`
@@ -123,15 +124,16 @@ All three hosts drive the same MCP server and shared workflow specs from `comman
 | `/agestra idea [topic]` | Discover improvements by comparing with similar projects |
 | `/agestra design [subject]` | Explore architecture and design trade-offs before implementation |
 | `/agestra setup` | Initial AI provider selection and setup |
-| `/agestra implement [task]` | Execute implementation in Claude-only or Multi-AI mode |
+| `/agestra implement [task]` | Execute implementation through Leader-host-only or suggested AI distribution mode |
 
-When external providers are available, text commands (review, design, idea) go directly to debate mode for multi-AI cross-validation. When no providers are detected, Claude works alone automatically.
+When external providers are available, text commands (review, design, idea) go directly to consensus debate mode for multi-AI cross-validation. When no providers are detected, the current leader host works with its local specialist agent automatically. Implementation requests first classify the task and can ask whether to propose an AI task distribution.
 
 ## Agents
 
 | Agent | Model | Role |
 |-------|-------|------|
 | `agestra-team-lead` | Sonnet | Full orchestrator — environment check, quality-based provider routing, work mode selection, CLI worker supervision, QA loop |
+| `agestra-implementer` | Sonnet | Scoped implementation executor — code edits, test updates, local verification |
 | `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 |
@@ -147,8 +149,11 @@ When external providers are available, text commands (review, design, idea) go d
 | `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 |
+| `setup` | Initial provider selection and `providers.config.json` write |
 | `design` | Architecture exploration workflow with multi-AI mode selection |
 | `idea` | Improvement discovery workflow with multi-AI mode selection |
+| `review` | Code quality / security / hardcoding review workflow with multi-AI mode selection |
+| `leader` | Multi-AI/provider orchestration entry — catches explicit provider, debate, consensus, or cross-validation signals, classifies the domain, and hands off to `agestra-team-lead` |
 
 ---
 
@@ -178,11 +183,11 @@ Turborepo monorepo with 9 packages:
 
 ### Work Modes
 
-**Text work** (review, design, idea): providers available → debate mode; no providers → Claude only
+**Text work** (review, design, idea): providers available → consensus debate mode; no providers → Leader-host 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.
+- **Leader-host only** — `agestra-implementer` applies scoped code changes; reviewer/QA verify.
+- **Suggested AI distribution** — the team lead proposes a routing table, asks for approval, then dispatches Codex/Gemini CLI workers for suitable code edits and Ollama for simple/repetitive proposal work.
 
 ---
 
@@ -283,7 +288,7 @@ Turborepo monorepo with 9 packages:
 
 ### providers.config.json
 
-Created by `/agestra setup`. The file lives at a single plugin-scoped location (resolution order: `AGESTRA_CONFIG_PATH` env var → `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json`). It is not meant to sit in the project repo and is gitignored accordingly.
+Created by `/agestra setup`. The default location is the host-shared `~/.agestra/providers.config.json`. Resolution order is `AGESTRA_CONFIG_PATH` env var → existing `~/.agestra/providers.config.json` → existing legacy `$CLAUDE_PLUGIN_ROOT/providers.config.json` → `~/.agestra/providers.config.json` for new writes. It is not meant to sit in the project repo and is gitignored accordingly.
 
 | Field | Description |
 |-------|-------------|
@@ -334,6 +339,7 @@ agestra/
 ├── .gemini/
 │   └── commands/
 │       └── agestra/
+│           ├── setup.toml   # /agestra:setup in Gemini CLI
 │           ├── review.toml  # /agestra:review in Gemini CLI
 │           ├── design.toml  # /agestra:design in Gemini CLI
 │           ├── idea.toml    # /agestra:idea in Gemini CLI
@@ -347,6 +353,7 @@ agestra/
 │   ├── agestra-reviewer.md  # Strict quality verifier (Opus)
 │   ├── agestra-designer.md  # Architecture explorer (Opus)
 │   ├── agestra-ideator.md   # Improvement discoverer (Sonnet)
+│   ├── agestra-implementer.md # Scoped implementation executor (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)
@@ -355,7 +362,12 @@ agestra/
 │   ├── worker-manage.md     # CLI worker management
 │   ├── cancel.md            # Graceful operation cancellation
 │   ├── build-fix.md         # Build error auto-repair
-│   └── trace.md             # Execution timeline viewer
+│   ├── trace.md             # Execution timeline viewer
+│   ├── setup.md             # Initial provider selection
+│   ├── design.md            # Architecture exploration workflow
+│   ├── idea.md              # Improvement discovery workflow
+│   ├── review.md            # Code quality review workflow
+│   └── leader.md            # Multi-AI orchestration entry router
 ├── hooks/
 │   └── user-prompt-submit.md  # Tool recommendation hook
 ├── dist/

package/README.zh.md

@@ -84,7 +84,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 | `/agestra setup` | 初始 AI 提供方选择与设置 |
 | `/agestra implement [task]` | 以 Claude only 或 Multi-AI 模式执行实现 |
 
-当外部提供方可用时，文本命令（review、design、idea）直接进入辩论模式，进行多 AI 交叉验证。当未检测到提供方时，Claude 自动独立工作。
+当外部提供方可用时，文本命令（review、design、idea）直接进入终极辩论模式，进行多 AI 交叉验证。当未检测到提供方时，Claude 自动独立工作。
 
 ## 代理
 
@@ -106,8 +106,11 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 | `cancel` | 安全停止 worker、辩论、链路和任务 |
 | `build-fix` | 自动诊断并修复 build/typecheck/lint 错误 |
 | `trace` | 查看代理执行时间线与流程图 |
+| `setup` | 初始提供方选择与 `providers.config.json` 写入 |
 | `design` | 包含 Multi-AI 模式选择的架构探索工作流 |
 | `idea` | 包含 Multi-AI 模式选择的改进发现工作流 |
+| `review` | 包含 Multi-AI 模式选择的代码质量·安全·硬编码审查工作流 |
+| `leader` | 多AI/提供方编排入口 — 捕获明确的提供方、辩论、共识或交叉验证信号，进行领域分类后委托给 `agestra-team-lead` |
 
 ---
 
@@ -137,7 +140,7 @@ Gemini 会结合仓库根目录下的 [GEMINI.md](GEMINI.md) 与 [`.gemini/comma
 
 ### 工作模式
 
-**文本工作**（review、design、idea）：有提供方 → 辩论模式；无提供方 → Claude only
+**文本工作**（review、design、idea）：有提供方 → 终极辩论模式；无提供方 → Claude only
 
 **实现工作**（team-lead orchestration）：
 - **Claude만으로** — Claude 直接结合项目/全局代理完成实现。
@@ -314,7 +317,12 @@ agestra/
 │   ├── worker-manage.md     # CLI Worker 管理
 │   ├── cancel.md            # 安全取消操作
 │   ├── build-fix.md         # 构建错误自动修复
-│   └── trace.md             # 执行时间线查看器
+│   ├── trace.md             # 执行时间线查看器
+│   ├── setup.md             # 初始提供方选择
+│   ├── design.md            # 架构探索工作流
+│   ├── idea.md              # 改进发现工作流
+│   ├── review.md            # 代码质量审查工作流
+│   └── leader.md            # 多AI 编排路由器
 ├── hooks/
 │   └── user-prompt-submit.md  # 工具推荐 hook
 ├── dist/

package/agents/agestra-designer.md

@@ -1,138 +1,139 @@
----
-name: agestra-designer
-description: |
-  Pre-implementation design explorer using Socratic questioning. Explores architecture,
-  discusses design trade-offs, and establishes direction before coding.
-
-  <example>
-  Context: User needs to plan architecture before implementing
-  user: "이 기능 어떻게 설계하면 좋을까?"
-  assistant: "I'll use the agestra-designer agent to explore architecture approaches."
-  <commentary>
-  User wants design exploration before coding — designer asks clarifying questions and proposes approaches.
-  </commentary>
-  </example>
-
-  <example>
-  Context: User is comparing implementation approaches
-  user: "REST vs GraphQL, 어떤 방향으로 가야할지 고민이야"
-  assistant: "I'll use the agestra-designer agent to analyze trade-offs between the approaches."
-  <commentary>
-  Design trade-off discussion — designer explores pros/cons of each approach.
-  </commentary>
-  </example>
-model: opus
-color: blue
----
-
-<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>
+---
+name: agestra-designer
+description: |
+  Pre-implementation design explorer using Socratic questioning. Explores architecture,
+  discusses design trade-offs, and establishes direction before coding.
+
+  <example>
+  Context: User needs to plan architecture before implementing
+  user: "이 기능 어떻게 설계하면 좋을까?"
+  assistant: "I'll use the agestra-designer agent to explore architecture approaches."
+  <commentary>
+  User wants design exploration before coding — designer asks clarifying questions and proposes approaches.
+  </commentary>
+  </example>
+
+  <example>
+  Context: User is comparing implementation approaches
+  user: "REST vs GraphQL, 어떤 방향으로 가야할지 고민이야"
+  assistant: "I'll use the agestra-designer agent to analyze trade-offs between the approaches."
+  <commentary>
+  Design trade-off discussion — designer explores pros/cons of each approach.
+  </commentary>
+  </example>
+model: opus
+color: blue
+disallowedTools: Edit, NotebookEdit
+---
+
+<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>