sopaco · sopaco · Apr 5, 2026 · Apr 5, 2026
diff --git a/.ai-context/core/modules.map b/.ai-context/core/modules.map
@@ -76,8 +76,10 @@ create_evolution_iteration() → prepare_workspace(inheritance) → inject_knowl
 `crates/cowork-core/src/pipeline/`
 - `mod.rs` - Stage trait, stage factory
 - `executor/mod.rs` - IterationExecutor (main orchestrator)
-- `executor/interaction_ext.rs` - HITL flow
-- `stages/*.rs` - Individual stage implementations
+- `executor/interaction_ext.rs` - HITL flow, ConfirmationAction enum
+- `executor/knowledge.rs` - Knowledge generation and injection
+- `executor/workspace.rs` - Workspace preparation and inheritance
+- `stages/*.rs` - Individual stage implementations (idea, prd, design, plan, coding, check, delivery)
 
 ### Domain Module
 `crates/cowork-core/src/domain/`
@@ -90,9 +92,19 @@ create_evolution_iteration() → prepare_workspace(inheritance) → inject_knowl
 - `file_tools.rs` - ReadFile, WriteFile, ListFiles
 - `data_tools.rs` - Requirement/Feature/Task CRUD
 - `hitl_tools.rs` - Review, Feedback
+- `hitl_content_tools.rs` - Content review and editing
+- `test_lint_tools.rs` - RunCommand, ExecuteShellCommand, CheckTests, CheckLint
 - `memory_tools.rs` - Query, Save, Promote
 - `artifact_tools.rs` - Save stage artifacts
+- `load_artifacts.rs` - LoadIdea, LoadPrdDoc, LoadFeedbackHistory
+- `control_tools.rs` - Pipeline control
+- `goto_stage_tool.rs` - GotoStage (backward only)
+- `validation_tools.rs` - CheckFeatureCoverage, CheckTaskDependencies
+- `knowledge_tools.rs` - LoadBaseKnowledge, SaveKnowledgeSnapshot
 - `pm_tools.rs` - PM Agent tools
+- `deployment_tools.rs` - CopyWorkspaceToProject
+- `legacy_project_analyzer_tools.rs` - ImportProject
+- `mcp_tools.rs` - MCP (Model Context Protocol) remote server integration
 
 ### Persistence Module
 `crates/cowork-core/src/persistence/`
@@ -102,12 +114,51 @@ create_evolution_iteration() → prepare_workspace(inheritance) → inject_knowl
 
 ### Agents Module
 `crates/cowork-core/src/agents/`
-- `mod.rs` - All agent builders
+- `mod.rs` - Agent exports
+- `iterative_assistant.rs` - Main ADK-based assistant
 - `external_coding_agent.rs` - ACP integration
+- `legacy_project_analyzer.rs` - Legacy project import agent
 
 ### Instructions Module
 `crates/cowork-core/src/instructions/`
-- `*.rs` - Prompts for each stage
+- `*.rs` - Prompts for each stage (Actor/Critic pairs for critical stages)
+
+### Config Definition Module
+`crates/cowork-core/src/config_definition/`
+- `agent_definition.rs` - AgentDefinition, AgentType
+- `stage_definition.rs` - StageDefinition, StageType, HookConfig
+- `flow_definition.rs` - FlowDefinition, StageReference
+- `integration_definition.rs` - IntegrationDefinition, IntegrationType
+- `registry.rs` - ConfigRegistry, global registry singleton
+- `validator.rs` - ConfigValidator
+- `agent_factory.rs` - create_agent_for_stage, create_agent_from_config
+- `default_configs/` - Built-in JSON configurations
+
+### Skills Module
+`crates/cowork-core/src/skills/`
+- `manager.rs` - SkillManager, SkillIndex, SkillMatch
+- Skill discovery, selection, and injection (agentskills.io standard)
+
+### Integration Module
+`crates/cowork-core/src/integration/`
+- `hooks.rs` - HookManager, HookExecutionContext
+- `adapters.rs` - IntegrationAdapter, AdapterError
+- `rest_adapter.rs` - RestAdapter for HTTP integrations
+
+### Importer Module
+`crates/cowork-core/src/importer/`
+- Project analysis, artifact generation, import configuration
+
+### ACP Module
+`crates/cowork-core/src/acp/`
+- Agent Client Protocol for external coding agent communication
+
+### Runtime Modules
+`crates/cowork-core/src/`
+- `project_runtime.rs` - Runtime configuration for generated projects
+- `runtime_analyzer.rs` - Runtime analysis and framework detection
+- `runtime_security.rs` - Security checking for runtime operations
+- `tech_stack.rs` - Technology stack detection
 
 ## QUICK NAVIGATION BY TASK
 
@@ -120,4 +171,9 @@ create_evolution_iteration() → prepare_workspace(inheritance) → inject_knowl
 | Add agent instruction | `instructions/` |
 | Modify storage | `persistence/` + `domain/` |
 | Add CLI command | `cowork-cli/src/commands/` |
-| Modify GUI | `cowork-gui/src/` (frontend) or `src-tauri/` (backend) |
+| Modify GUI | `cowork-gui/src/` (frontend) or `src-tauri/` (backend) |
+| Add config definition | `config_definition/` + `default_configs/` |
+| Add skill | `skills/` or external `.skills/` directory |
+| Add integration | `integration/` + IntegrationDefinition |
+| Modify external agent | `acp/` + `agents/external_coding_agent.rs` |
+| Import legacy project | `importer/` + `agents/legacy_project_analyzer.rs` |
diff --git a/.ai-context/domains/domain-logic.md b/.ai-context/domains/domain-logic.md
@@ -40,12 +40,36 @@ Draft → Running → [Paused] → Completed | Failed
 
 ## Knowledge Types
 
-| Type | Scope |
-|------|-------|
-| Decision | Project-level |
-| Pattern | Project-level |
-| Issue | Iteration → Project |
-| Learning | Iteration-level |
+| Type | Scope | Description |
+|------|-------|-------------|
+| Decision | Project-level | Architecture decisions with rationale |
+| Pattern | Project-level | Reusable patterns with tags and usage |
+| Issue | Iteration → Project | Known issues and tech debt |
+| Learning | Iteration-level | Session-specific learnings |
+| Insight | Stage-level | Observations during execution |
+
+## Memory Management
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| ProjectMemory | `domain/memory.rs` | Cross-iteration knowledge aggregate |
+| IterationKnowledge | `domain/memory.rs` | Single iteration knowledge snapshot |
+| MemoryStore | `persistence/memory_store.rs` | JSON-based memory persistence |
+| Knowledge Tools | `tools/knowledge_tools.rs` | Load, save, promote knowledge |
+| Knowledge Generator | `pipeline/executor/knowledge.rs` | Post-delivery knowledge extraction |
+
+### Knowledge Promotion Flow
+```
+Insight (during execution) 
+  → SaveInsightTool 
+  → PromoteToDecisionTool / PromoteToPatternTool 
+  → ProjectMemory (decision/pattern)
+```
+
+### Knowledge Query Scopes
+- `project`: Historical project-level knowledge
+- `iteration`: Current iteration-specific knowledge
+- `latest`: Merged view with context aggregation
 
 ---
 **Note**: For struct fields, read `domain/*.rs` directly.
diff --git a/.ai-context/domains/pipeline.md b/.ai-context/domains/pipeline.md
@@ -4,7 +4,7 @@
 
 | Stage | HITL | Pattern | Output |
 |-------|------|---------|--------|
-| Idea | No | Simple | idea.md |
+| Idea | Yes | Simple | idea.md |
 | PRD | Yes | Actor-Critic | prd.md |
 | Design | Yes | Actor-Critic | design.md |
 | Plan | Yes | Actor-Critic | plan.md |
@@ -17,7 +17,7 @@
 ```
 prepare_workspace() → stages[idea→delivery] → generate_knowledge()
                               ↓
-                    HITL gate (critical stages)
+                    HITL gate (all stages)
 ```
 
 ## Actor-Critic Pattern
@@ -27,6 +27,7 @@ Actor generates → Critic validates → HITL confirms → [Pass|Feedback loop]
 ```
 
 **Critical**: LoopAgent uses `max_iterations=1` (see ADR-001)
+**Coding Stage**: Allows `max_iterations=5` for iterative code refinement (ADR-003)
 
 ## Agent Types
 
@@ -36,13 +37,36 @@ Actor generates → Critic validates → HITL confirms → [Pass|Feedback loop]
 | Actor-Critic | PRD, Design, Plan, Coding | LoopAgent |
 | PM Agent | Post-Delivery | Interactive |
 
+## IterationExecutor Architecture
+
+The executor uses a modular architecture in `pipeline/executor/`:
+
+| Module | Purpose |
+|--------|---------|
+| `mod.rs` | Main entry, iteration lifecycle, stage execution loop |
+| `interaction_ext.rs` | ConfirmationAction enum, HITL flow extension |
+| `knowledge.rs` | Knowledge generation, injection, document summaries |
+| `workspace.rs` | Workspace preparation, inheritance (Full/Partial/None) |
+
+### Knowledge Injection (knowledge.rs)
+- Priority: Knowledge Summary → fallback to baseline artifacts
+- Injects project context into evolution iterations
+
+### Inheritance Flow (workspace.rs)
+- `None`: Fresh start, no files inherited
+- `Partial`: Copy code files only, skip artifacts/
+- `Full`: Copy all files and artifacts
+
 ## Code Locations
 
 | Component | Location |
 |-----------|----------|
 | Stage trait | `pipeline/mod.rs` |
 | Executor | `pipeline/executor/mod.rs` |
+| HITL extension | `pipeline/executor/interaction_ext.rs` |
+| Knowledge logic | `pipeline/executor/knowledge.rs` |
+| Workspace logic | `pipeline/executor/workspace.rs` |
 | Stages | `pipeline/stages/*.rs` |
-| Agent builders | `agents/mod.rs` |
-| Instructions | `instructions/*.rs` |
+| Agent builders | `agents/iterative_assistant.rs` |
 | External agent | `agents/external_coding_agent.rs` |
+| Instructions | `instructions/*.rs` |
diff --git a/.ai-context/domains/tools.md b/.ai-context/domains/tools.md
@@ -7,21 +7,38 @@
 | File | `file_tools.rs` | ReadFile, WriteFile, ListFiles |
 | Data | `data_tools.rs` | CreateRequirement, AddFeature, GetRequirements, CreateTask |
 | HITL | `hitl_tools.rs` | ReviewWithFeedback, ProvideFeedback |
+| HITL Content | `hitl_content_tools.rs` | ReviewAndEditContentTool, ReviewAndEditFileTool |
+| Test/Lint | `test_lint_tools.rs` | RunCommand, ExecuteShellCommand, CheckTests, CheckLint |
 | Memory | `memory_tools.rs` | QueryMemory, SaveInsight, PromoteToDecision |
 | Artifact | `artifact_tools.rs` | SaveIdea, SavePrdDoc, SaveDesignDoc |
 | Load | `load_artifacts.rs` | LoadIdea, LoadPrdDoc, LoadFeedbackHistory |
-| Control | `control_tools.rs`, `goto_stage_tool.rs` | GotoStage |
+| Control | `control_tools.rs`, `goto_stage_tool.rs` | GotoStage (backward only) |
 | Validation | `validation_tools.rs` | CheckFeatureCoverage, CheckTaskDependencies |
-| Test/Lint | `test_lint_tools.rs` | RunCommand, CheckTests, CheckLint |
 | Knowledge | `knowledge_tools.rs` | LoadBaseKnowledge, SaveKnowledgeSnapshot |
 | PM | `pm_tools.rs` | PMGotoStage, PMCreateIteration, PMRespond |
 | Deploy | `deployment_tools.rs` | CopyWorkspaceToProject |
 | Import | `legacy_project_analyzer_tools.rs` | ImportProject |
+| MCP | `mcp_tools.rs` | MCP remote server integration (Model Context Protocol) |
+
+## Tool Notification System
+
+Tools broadcast calls and results to GUI via global notifier (`tools/mod.rs`):
+- `notify_tool_call(tool_name, args)` - called before tool execution
+- `notify_tool_result(tool_name, result)` - called after tool execution
+- Registered by GUI backend at startup via `set_tool_notify_callback()`
+
+## Parameter Helpers
+
+Safe parameter extraction utilities in `tools/mod.rs`:
+- `get_required_string_param(args, key)` - required string from JSON args
+- `get_optional_string_param(args, key)` - optional string from JSON args
+- `get_required_array_param(args, key)` - required array from JSON args
 
 ## Security
 
 - All file ops validated within workspace
 - Dangerous commands blocked
+- Path traversal prevention (UNC normalization on Windows)
 
 ## Location
 

diff --git a/.ai-context/project.snapshot b/.ai-context/project.snapshot
@@ -16,12 +16,22 @@ path: crates/cowork-core/
 key_modules:
   - pipeline: 7-stage workflow orchestration
   - domain: Project, Iteration, Memory aggregates (DDD)
-  - tools: 30+ ADK tools
+  - tools: 35+ ADK tools (file, data, HITL, memory, MCP, validation, etc.)
   - persistence: JSON-based storage
   - interaction: CLI/GUI abstraction
-  - agents: Agent builders
+  - agents: Agent builders (iterative_assistant, external_coding_agent, legacy_project_analyzer)
   - instructions: Prompts for each stage
-  - config_definition: data-driven configuration system
+  - config_definition: data-driven configuration system (Agent, Stage, Flow, Skill, Integration)
+  - skills: agentskills.io standard skill management and injection
+  - integration: external system integration with hooks and REST adapter
+  - importer: legacy project analysis and import
+  - acp: Agent Client Protocol for external coding agents
+  - llm: rate-limited LLM client factory
+  - data: data models and types
+  - project_runtime: runtime configuration for generated projects
+  - runtime_analyzer: runtime analysis and configuration detection
+  - runtime_security: security checking for runtime operations
+  - tech_stack: technology stack detection and configuration
 
 ### cowork-cli
 path: crates/cowork-cli/
@@ -77,8 +87,20 @@ Fields: llm.api_base_url, llm.api_key, llm.model_name, embedding.*
 
 ## EXTERNAL INTEGRATIONS
 
-- **ACP**: `acp/` - External coding agent integration (opencode, iflow, codex, etc.)
-- **Skills**: `skills/` - Domain-specific capability injection (agentskills.io)
+- **ACP**: `acp/` - External coding agent integration (opencode, iflow, codex, gemini, claude)
+  - Agent Client Protocol for process-based communication
+  - Configurable via config.toml `[coding_agent]` section
+  - Supports stdio and websocket transports
+
+- **Skills**: `skills/` - Domain-specific capability injection (agentskills.io standard)
+  - SkillManager for discovery, indexing, and selection
+  - SkillInjector for prompt and tool injection
+  - Markdown-based skill definitions with semantic matching
+
+- **Integration**: `integration/` - External system integration framework
+  - HookManager for lifecycle event hooks
+  - REST adapter for HTTP-based integrations
+  - Configurable via IntegrationDefinition
 
 ---
 **Note**: For detailed implementations, see corresponding source files.
diff --git a/litho.docs/en/1.Overview.md b/litho.docs/en/1.Overview.md
@@ -33,6 +33,7 @@ The platform delivers measurable value through:
 | **Knowledge Retention** | Preserves architectural decisions, design patterns, and technical insights across iterations, preventing context loss in long-running projects |
 | **Standardized Methodology** | Provides teams with consistent development practices through structured stage gates and validation protocols |
 | **Local Execution** | Operates entirely on local infrastructure without cloud dependencies, ensuring data privacy and reducing operational costs |
+| **External Capability Extension** | Integrates external AI services via Model Context Protocol (MCP), expanding agent capabilities with Tavily search, DeepWiki documentation queries, and other third-party MCP servers |
 
 ### 2.3 Technical Characteristics
 
@@ -44,6 +45,7 @@ The platform delivers measurable value through:
 - **Persistence**: JSON-based file storage with workspace containment
 
 **Key Technical Features**:
+- **External Integration**: Model Context Protocol (MCP) HTTP client via adk-tool
 - **Rate-Limited LLM Integration**: Decorator-pattern implementation enforcing 30 requests/minute with single concurrency control
 - **Event-Driven Communication**: Real-time bidirectional IPC between Tauri backend and React frontend via event emission
 - **Security-First Operations**: Path validation and workspace containment for all file system operations
@@ -116,7 +118,7 @@ The system boundary encompasses the following core architectural components:
 | **Agent Instruction System** | ~2000 lines of prompt engineering (Actor/Critic instructions per stage, knowledge generation, Legacy Project Analyzer) |
 | **Configuration System** | Config Registry, Agent/Stage/Flow/Skill/Integration definitions, user config management, validation |
 | **Skills Module** | adk-skill integration (agentskills.io standard), skill discovery, selection, and injection |
-| **Tool Ecosystem** | 30+ ADK Tools (File Tools, Data Tools, Validation Tools, HITL Tools, Memory Tools, Deployment Tools, Legacy Project Analysis Tools) |
+| **Tool Ecosystem** | 40+ ADK Tools (File Tools, Data Tools, Validation Tools, HITL Tools, Memory Tools, Deployment Tools, Legacy Project Analysis Tools), with MCP Remote Tool Integration (Tavily, DeepWiki, etc.) |
 | **Memory Management** | ProjectMemory and IterationKnowledge domains, query indexing, knowledge promotion workflows |
 | **Specialized Agents** | PM Agent for post-delivery interaction, Legacy Project Analyzer for existing project import and reverse engineering, Knowledge Generation Agent for insight extraction |
 | **Importer Module** | Project analyzer, artifact generator, import configuration, technology stack detection |
@@ -157,12 +159,14 @@ C4Context
     System_Ext(editor, "External Editor", "System default editor for HITL content review")
     System_Ext(devserver, "Development Server", "Vite/similar for live application preview")
     System_Ext(tauri, "Tauri Runtime", "Desktop GUI framework and native APIs")
+    System_Ext(mcp_servers, "MCP Servers", "External AI services providing tools via Model Context Protocol (Tavily search, DeepWiki docs)")
 
     Rel(individual, gui, "Interacts with via desktop application")
     Rel(individual, cli, "Executes commands via terminal")
     Rel(team, gui, "Collaborates through shared project memory")
 
     Rel(core, llm, "Sends API requests\n(Rate-limited: 30 req/min)", "HTTPS/JSON")
+    Rel(core, mcp_servers, "Queries for external tools and services", "MCP/HTTP")
     Rel(core, fs, "Reads/Writes project files\n(Workspace-contained)", "File I/O")
     Rel(core, shell, "Executes validation commands\nand build processes", "Process Execution")
     Rel(core, editor, "Invokes for content\nreview and editing", "System Call")
@@ -215,6 +219,13 @@ C4Context
 - **Architecture Role**: Provides the presentation layer container for the React frontend, enabling system tray integration, native menus, and secure context isolation
 - **Data Exchange**: Command invocations (invoke), event emissions (agent events, streaming responses), and binary asset management
 
+
+#### 5.2.7 MCP Servers
+- **Interaction Type**: HTTP-based Protocol Integration
+- **Purpose**: Extend agent capabilities with external AI services through Model Context Protocol (MCP). Currently supports Tavily for web search and AI-powered research, and DeepWiki for code documentation queries.
+- **Configuration**: Managed via `config.toml` under `[mcp]` section with `tavily_api_key` and `deepwiki_enabled` flags. Automatic initialization at application startup connects to configured MCP servers and injects their toolsets into all Agents.
+- **Data Exchange**: MCP HTTP requests/responses; remote tools appear as native ADK tools to agents after injection.
+
 ## 6. Key Architectural Decisions
 
 ### 6.1 Multi-Stage Pipeline with Actor-Critic Pattern