agestra 4.1.0

package/README.ko.md

@@ -0,0 +1,241 @@
+# Agestra
+
+**Agent + Orchestra** — 여러 AI 공급자를 Claude Code에서 오케스트레이션하는 플러그인.
+
+[English](README.md) | [한국어](README.ko.md)
+
+Agestra는 Ollama(로컬), Gemini CLI, Codex CLI를 Claude Code에 플러그형으로 연결합니다. 멀티에이전트 토론, 병렬 작업 분배, 교차 검증, 지속적 GraphRAG 메모리 시스템을 28개 MCP 도구로 제공합니다.
+
+## 빠른 시작
+
+```bash
+claude plugin add agestra
+```
+
+끝. Agestra가 첫 사용 시 사용 가능한 공급자(Ollama, Gemini CLI, Codex CLI)를 자동 감지합니다.
+
+### 사전 요구사항
+
+최소 하나의 AI 공급자가 설치되어야 합니다:
+
+| 공급자 | 설치 | 유형 |
+|--------|------|------|
+| [Ollama](https://ollama.com/) | `curl -fsSL https://ollama.com/install.sh \| sh` | 로컬 LLM |
+| [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` | 클라우드 |
+
+---
+
+## 철학
+
+**멀티 AI는 검증을 위한 것이지, 토큰 절약을 위한 것이 아닙니다.** 리뷰, 설계 탐색, 아이디어 발굴 워크플로우는 검증 프로세스로 설계되었습니다 — 속도를 위한 병렬화가 아니라, 사각지대를 잡기 위해 여러 AI 공급자로부터 독립적인 의견을 얻는 것입니다.
+
+## 커맨드
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/agestra review [대상]` | 코드 품질, 보안, 통합 완성도 검증 |
+| `/agestra idea [주제]` | 유사 프로젝트 비교를 통한 개선점 발굴 |
+| `/agestra design [주제]` | 구현 전 아키텍처 및 설계 트레이드오프 탐색 |
+
+각 커맨드는 선택지를 제시합니다: **Claude만**, **비교** (여러 AI 나란히), **토론** (구조화된 멀티AI 논의), **기타** (사용자 지정).
+
+## 에이전트
+
+| 에이전트 | 모델 | 역할 |
+|----------|------|------|
+| `reviewer` | Opus | 엄격한 품질 검증 — 보안, 고아 시스템, 스펙 이탈, 테스트 공백 |
+| `designer` | Opus | 아키텍처 탐색 — 소크라테스식 질문, 트레이드오프 분석 |
+| `ideator` | Sonnet | 개선점 발굴 — 웹 리서치, 경쟁 분석 |
+| `moderator` | Sonnet | 토론 진행 — 중립, 턴 관리, 합의 판정 |
+
+---
+
+## 아키텍처
+
+Turborepo 모노레포, 8개 패키지:
+
+| 패키지 | 설명 |
+|--------|------|
+| `@agestra/core` | `AIProvider` 인터페이스, 레지스트리, 설정 로더, CLI 러너, 원자적 쓰기, 작업 큐 |
+| `@agestra/provider-ollama` | Ollama HTTP 어댑터 (모델 자동 감지) |
+| `@agestra/provider-gemini` | Google Gemini CLI 어댑터 |
+| `@agestra/provider-codex` | OpenAI Codex CLI 어댑터 |
+| `@agestra/agents` | 토론 엔진, 작업 분배기, 교차 검증기, 세션 관리자 |
+| `@agestra/workspace` | 코드 리뷰 워크플로우용 문서 관리자 |
+| `@agestra/memory` | GraphRAG — FTS5 + 벡터 + 지식 그래프 하이브리드 검색, 실패 추적 |
+| `@agestra/mcp-server` | MCP 프로토콜 레이어, 28개 도구, 디스패치 |
+
+### 설계 원칙
+
+- **공급자 추상화** — 모든 백엔드가 `AIProvider`(`chat`, `healthCheck`, `getCapabilities`)를 구현. 기존 코드 수정 없이 새 공급자 추가 가능.
+- **제로 설정** — 시작 시 공급자를 자동 감지. 수동 설정 불필요.
+- **플러그인 네이티브** — Claude Code 플러그인으로 설치. Skills, hooks, MCP 서버가 함께 번들.
+- **모듈형 디스패치** — 각 도구 카테고리가 `getTools()` + `handleTool()`을 내보내는 독립 모듈. 서버가 동적으로 수집·디스패치.
+- **원자적 쓰기** — 모든 파일 연산이 임시 파일 → rename 방식. 크래시 시 손상 방지.
+- **실패 추적** — 실패한 접근법이 GraphRAG에 자동 기록, 이후 프롬프트에 주입.
+
+---
+
+## 도구 (28개)
+
+### AI 채팅 (3개)
+
+| 도구 | 설명 |
+|------|------|
+| `ai_chat` | 특정 공급자와 채팅 |
+| `ai_analyze_files` | 파일을 디스크에서 읽어 공급자에게 질문과 함께 전송 |
+| `ai_compare` | 같은 프롬프트를 여러 공급자에 보내 응답 비교 |
+
+### 에이전트 오케스트레이션 (9개)
+
+| 도구 | 설명 |
+|------|------|
+| `agent_debate_start` | 다중 공급자 토론 시작 (논블로킹, 품질 루프 + 검증자 옵션) |
+| `agent_debate_status` | 토론 상태 및 트랜스크립트 확인 |
+| `agent_debate_create` | 턴 기반 토론 세션 생성 (토론 ID 반환) |
+| `agent_debate_turn` | 공급자 1턴 실행; `provider: "claude"`로 Claude 독립 참여 지원 |
+| `agent_debate_conclude` | 토론 종료 및 최종 트랜스크립트 생성 |
+| `agent_assign_task` | 특정 공급자에게 작업 위임 |
+| `agent_task_status` | 작업 완료 상태 및 결과 확인 |
+| `agent_dispatch` | 공급자 간 병렬 작업 분배 (의존성 순서 지원) |
+| `agent_cross_validate` | 출력 교차 검증 (에이전트 등급 검증자만 가능) |
+
+### 워크스페이스 (4개)
+
+| 도구 | 설명 |
+|------|------|
+| `workspace_create_review` | 파일과 규칙이 포함된 코드 리뷰 문서 생성 |
+| `workspace_request_review` | 공급자에게 문서 리뷰 요청 |
+| `workspace_add_comment` | 리뷰에 코멘트 추가 |
+| `workspace_read` | 리뷰 내용 읽기 |
+
+### 공급자 관리 (2개)
+
+| 도구 | 설명 |
+|------|------|
+| `provider_list` | 공급자 목록 (상태, 능력 포함) |
+| `provider_health` | 공급자 상태 체크 |
+
+### Ollama (2개)
+
+| 도구 | 설명 |
+|------|------|
+| `ollama_models` | 설치된 모델 및 크기 목록 |
+| `ollama_pull` | 모델 다운로드 |
+
+### 메모리 (6개)
+
+| 도구 | 설명 |
+|------|------|
+| `memory_search` | 하이브리드 검색 (FTS5 + 벡터 + 그래프) |
+| `memory_index` | 파일/디렉토리를 메모리에 인덱싱 |
+| `memory_store` | 지식 노드 저장 (fact, decision, dead_end, finding) |
+| `memory_dead_ends` | 이전 실패 접근법 검색 (반복 방지) |
+| `memory_context` | 토큰 예산 내 관련 컨텍스트 조립 |
+| `memory_add_edge` | 지식 노드 간 관계 엣지 생성 |
+
+### 작업 (2개)
+
+| 도구 | 설명 |
+|------|------|
+| `cli_job_submit` | 장시간 CLI 작업을 백그라운드에 제출 |
+| `cli_job_status` | 작업 상태 확인 및 출력 조회 |
+
+---
+
+## 설정
+
+### 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/` | 백그라운드 작업 큐 |
+
+---
+
+## 개발
+
+```bash
+npm install        # 의존성 설치
+npm run build      # 전체 빌드 (Turborepo)
+npm test           # 전체 테스트 (Vitest)
+npm run bundle     # 단일 파일 플러그인 번들 (esbuild)
+npm run dev        # 워치 모드
+npm run lint       # 린트 (ESLint)
+npm run clean      # dist/ 삭제
+```
+
+### 프로젝트 구조
+
+```
+agestra/
+├── plugin.json              # Claude Code 플러그인 매니페스트
+├── commands/
+│   ├── review.md            # /agestra review — 품질 검증
+│   ├── idea.md              # /agestra idea — 개선점 발굴
+│   └── design.md            # /agestra design — 아키텍처 탐색
+├── agents/
+│   ├── reviewer.md          # 엄격한 품질 검증자 (Opus)
+│   ├── designer.md          # 아키텍처 탐색자 (Opus)
+│   ├── ideator.md           # 개선점 발굴자 (Sonnet)
+│   └── moderator.md         # 토론 진행자 (Sonnet)
+├── skills/
+│   └── provider-guide.md    # 공급자 사용 가이드라인 (skill)
+├── hooks/
+│   └── user-prompt-submit.md  # 도구 추천 hook
+├── dist/
+│   └── bundle.js            # 단일 파일 MCP 서버 번들
+├── scripts/
+│   └── bundle.mjs           # esbuild 번들 스크립트
+├── packages/
+│   ├── core/                # AIProvider 인터페이스, 레지스트리
+│   ├── provider-ollama/     # Ollama HTTP 어댑터
+│   ├── provider-gemini/     # Gemini CLI 어댑터
+│   ├── provider-codex/      # Codex CLI 어댑터
+│   ├── agents/              # 토론 엔진, 분배기, 교차 검증기
+│   ├── workspace/           # 코드 리뷰 문서 관리자
+│   ├── memory/              # GraphRAG: 하이브리드 검색, 실패 추적
+│   └── mcp-server/          # MCP 서버, 28개 도구, 디스패치
+├── package.json             # 워크스페이스 루트
+└── turbo.json               # Turborepo 파이프라인
+```
+
+### 새 공급자 추가
+
+1. `packages/provider-<이름>/`에 `AIProvider` 구현.
+2. `packages/mcp-server/src/index.ts`에 팩토리 추가.
+3. `npm run build && npm test`
+
+---
+
+## 제거
+
+```bash
+claude plugin remove agestra
+```
+
+프로젝트에 잔여 파일 없음. 깔끔한 제거.
+
+---
+
+## 라이선스
+
+GPL-3.0

package/README.md

@@ -0,0 +1,241 @@
+# Agestra
+
+**Agent + Orchestra** — A Claude Code plugin that orchestrates multiple AI providers.
+
+[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 28 MCP tools.
+
+## Quick Start
+
+```bash
+claude plugin add agestra
+```
+
+That's it. Agestra auto-detects available providers (Ollama, Gemini CLI, Codex CLI) on first use.
+
+### Prerequisites
+
+At least one AI provider must be installed:
+
+| Provider | Install | Type |
+|----------|---------|------|
+| [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 |
+
+---
+
+## Philosophy
+
+**Multi-AI is for verification, not token savings.** The review, design exploration, and idea generation workflows are structured as validation processes — getting independent opinions from multiple AI providers to catch blind spots, not to parallelize for speed.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/agestra review [target]` | Review code quality, security, and integration completeness |
+| `/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).
+
+## 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 |
+
+---
+
+## Architecture
+
+Turborepo monorepo with 8 packages:
+
+| Package | Description |
+|---------|-------------|
+| `@agestra/core` | `AIProvider` interface, registry, config loader, CLI runner, atomic writes, job queue |
+| `@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, 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, 28 tools, dispatch |
+
+### Design Principles
+
+- **Provider abstraction** — All backends implement `AIProvider` (`chat`, `healthCheck`, `getCapabilities`). New providers require no existing code changes.
+- **Zero-config** — Providers are auto-detected at startup. No manual configuration required.
+- **Plugin-native** — Installed as a Claude Code plugin. Skills, hooks, and MCP server are bundled together.
+- **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.
+
+---
+
+## Tools (28)
+
+### AI Chat (3)
+
+| Tool | Description |
+|------|-------------|
+| `ai_chat` | Chat with a specific provider |
+| `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 (9)
+
+| Tool | Description |
+|------|-------------|
+| `agent_debate_start` | Start a multi-provider debate (non-blocking, optional quality loop + validator) |
+| `agent_debate_status` | Check debate status and transcript |
+| `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_assign_task` | Delegate a task to a specific provider |
+| `agent_task_status` | Check task completion and result |
+| `agent_dispatch` | Distribute tasks across providers in parallel (dependency ordering) |
+| `agent_cross_validate` | Cross-validate outputs (agent-tier validators only) |
+
+### Workspace (4)
+
+| Tool | Description |
+|------|-------------|
+| `workspace_create_review` | Create a code review document with files and rules |
+| `workspace_request_review` | Request a provider to review a document |
+| `workspace_add_comment` | Add a comment to a review |
+| `workspace_read` | Read review contents |
+
+### Provider Management (2)
+
+| Tool | Description |
+|------|-------------|
+| `provider_list` | List providers with status and capabilities |
+| `provider_health` | Health check one or all providers |
+
+### Ollama (2)
+
+| Tool | Description |
+|------|-------------|
+| `ollama_models` | List installed models with sizes |
+| `ollama_pull` | Download a model |
+
+### Memory (6)
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Hybrid retrieval (FTS5 + vector + graph) |
+| `memory_index` | Index files/directories into memory |
+| `memory_store` | Store a knowledge node (fact, decision, dead_end, finding) |
+| `memory_dead_ends` | Search previous failures to avoid repeating them |
+| `memory_context` | Assemble relevant context within a token budget |
+| `memory_add_edge` | Create relationship edges between knowledge nodes |
+
+### Jobs (2)
+
+| Tool | Description |
+|------|-------------|
+| `cli_job_submit` | Submit a long-running CLI task to background |
+| `cli_job_status` | Check job status and output |
+
+---
+
+## Configuration
+
+### providers.config.json (Optional)
+
+Agestra auto-detects providers at startup. For manual control, create `providers.config.json` in the project root:
+
+| Field | Description |
+|-------|-------------|
+| `defaultProvider` | Provider ID when none specified |
+| `providers[].id` | Unique identifier |
+| `providers[].type` | `ollama`, `gemini-cli`, or `codex-cli` |
+| `providers[].enabled` | Load at startup |
+| `providers[].config` | Type-specific settings (host, timeout, etc.) |
+
+### Runtime Data
+
+Stored under `.agestra/` (gitignored):
+
+| Path | Purpose |
+|------|---------|
+| `.agestra/sessions/` | Debate and task session state |
+| `.agestra/workspace/` | Code review documents |
+| `.agestra/memory.db` | GraphRAG SQLite database |
+| `.agestra/.jobs/` | Background job queue |
+
+---
+
+## Development
+
+```bash
+npm install        # Install dependencies
+npm run build      # Build all packages (Turborepo)
+npm test           # Run all tests (Vitest)
+npm run bundle     # Build single-file plugin bundle (esbuild)
+npm run dev        # Watch mode
+npm run lint       # Lint (ESLint)
+npm run clean      # Remove dist/
+```
+
+### Project Structure
+
+```
+agestra/
+├── plugin.json              # Claude Code plugin manifest
+├── commands/
+│   ├── review.md            # /agestra review — quality verification
+│   ├── 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)
+├── skills/
+│   └── provider-guide.md    # Provider usage guidelines (skill)
+├── hooks/
+│   └── user-prompt-submit.md  # Tool recommendation hook
+├── dist/
+│   └── bundle.js            # Single-file MCP server bundle
+├── scripts/
+│   └── bundle.mjs           # esbuild bundle script
+├── packages/
+│   ├── core/                # AIProvider interface, registry
+│   ├── 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, 28 tools, dispatch
+├── package.json             # Workspace root
+└── turbo.json               # Turborepo pipeline
+```
+
+### Adding a Provider
+
+1. Create `packages/provider-<name>/` implementing `AIProvider`.
+2. Add a factory in `packages/mcp-server/src/index.ts`.
+3. `npm run build && npm test`
+
+---
+
+## Uninstall
+
+```bash
+claude plugin remove agestra
+```
+
+No residual files in your project. Clean removal.
+
+---
+
+## License
+
+GPL-3.0

package/agents/designer.md

@@ -0,0 +1,78 @@
+---
+name: designer
+description: 아키텍처 탐색, 설계 트레이드오프 논의, 구현 전 방향 수립에 사용. 소크라테스식 질문.
+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
+Ask questions to understand the user's idea. One question at a time. Focus on:
+- What problem does this solve **within this project**?
+- Who uses it?
+- What are the constraints (performance, compatibility, scope)?
+- What does "done" look like?
+
+### 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.
+</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>

package/agents/ideator.md

@@ -0,0 +1,113 @@
+---
+name: ideator
+description: 유사 프로젝트 비교, 사용자 불만 수집, 개선점 발굴, 새 기능 탐색에 사용.
+model: claude-sonnet-4-6
+---
+
+<Role>
+You are an idea and improvement discoverer. You research similar projects, collect user complaints and feature requests, compare capabilities, and generate actionable suggestions. You combine web research with codebase understanding to find opportunities.
+</Role>
+
+<Scope>
+You operate in two modes based on context:
+
+**Mode A: Existing project** — The codebase has a README or meaningful code.
+Research improvements, missing features, and competitive gaps for this project.
+
+**Mode B: New project** — The codebase is empty/new, but the user has a seed idea (e.g., "글쓰는 툴 만들고 싶어", "I want to build a writing tool").
+Research the landscape: what already exists, what users complain about, what gaps remain. Help the user shape their idea by showing what's out there.
+
+**Out of scope:** Requests with no seed idea at all (e.g., "돈 벌리는 거 뭐 없을까?", "what should I build?"). You need at least a domain or concept to anchor your research. Say so:
+
+> "I need at least a rough idea to research — a domain, a tool type, or a problem you want to solve. For example: 'a writing tool', 'a CLI for deployment', 'something for managing bookmarks'."
+</Scope>
+
+<Workflow>
+
+### Phase 1: Understand Scope
+Determine which mode to operate in:
+
+**If existing project (Mode A):**
+- Read the project's README and key files to understand what it does
+- Use Glob and Grep to map the current feature set
+- Identify the project's category and target audience
+
+**If new project with seed idea (Mode B):**
+- Clarify the seed idea: what domain? what type of tool? who would use it?
+- Use this as the anchor for all subsequent research
+- Skip codebase exploration (there's nothing to explore)
+
+### Phase 2: Research Similar Projects
+- Use WebSearch to find similar tools, libraries, and projects
+- Look for: direct competitors, adjacent tools, inspirational projects
+- Collect names, URLs, and key differentiators
+
+### Phase 3: Collect Pain Points
+- WebSearch for complaints about similar tools (GitHub issues, forums, discussions)
+- WebFetch relevant issue pages and discussion threads
+- Identify recurring themes in user feedback
+- Note what users wish existed but doesn't
+
+### Phase 4: Feature Comparison
+Build a comparison table:
+
+| Feature | This Project | Competitor A | Competitor B |
+|---------|-------------|-------------|-------------|
+| Feature 1 | Yes/No | Yes/No | Yes/No |
+
+### Phase 5: Generate Suggestions
+For each suggestion:
+- **Title** — clear, actionable name
+- **Category** — UX, Performance, Feature, Integration, DX
+- **Source** — where this idea came from (competitor, user complaint, own analysis)
+- **Priority** — HIGH / MEDIUM / LOW with rationale
+- **Effort** — estimated complexity
+- **Description** — what it does and why it matters
+
+### Phase 6: Prioritized Recommendations
+Present a ranked list with:
+1. Quick wins (high impact, low effort)
+2. Strategic investments (high impact, high effort)
+3. Nice-to-haves (low impact, low effort)
+</Workflow>
+
+<Tool_Usage>
+- **WebSearch**: Find similar projects, user complaints, feature discussions
+- **WebFetch**: Read specific pages for detailed analysis
+- **Read, Glob, Grep**: Understand current project capabilities
+</Tool_Usage>
+
+<Output_Format>
+## Research Summary
+
+### Similar Projects
+(list with URLs and key features)
+
+### User Pain Points
+(categorized complaints from research)
+
+### Feature Comparison
+(table)
+
+### Recommendations
+
+#### Quick Wins
+1. ...
+
+#### Strategic Investments
+1. ...
+
+#### Nice-to-Haves
+1. ...
+
+### Sources
+- [Source 1](url)
+- [Source 2](url)
+</Output_Format>
+
+<Constraints>
+- Always include source URLs for claims about other projects.
+- Do not fabricate features of competitors — verify via web research.
+- Prioritize actionable suggestions over theoretical improvements.
+- Present findings in the user's language.
+</Constraints>