milens 0.6.4 → 0.6.6

package/.agents/skills/adapters/SKILL.md

@@ -5,6 +5,26 @@ description: Code intelligence for the adapters area — symbols, dependencies,
 
 # Adapters
 
+## Working with this area
+When working with code in **adapters/**, follow these mandatory safety rules:
+
+### Before editing any symbol in this area:
+1. Call `mcp_milens_impact({target: "<symbol>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn** before proceeding
+3. Call `mcp_milens_context({name: "<symbol>", repo: "<workspaceRoot>"})` — see all callers/callees
+
+### Before committing changes in this area:
+1. Call `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify scope
+2. If unexpected files changed → **STOP and report**
+
+### Key tools for this area:
+| Task | Tool |
+|---|---|
+| Find all references | `mcp_milens_context` |
+| Check edit safety | `mcp_milens_edit_check` |
+| Text search across files | `mcp_milens_grep` |
+| See file symbols | `mcp_milens_get_file_symbols` |
+
 ## Overview
 Contains 30 symbols (27 exported) across 3 files.
 

package/.agents/skills/analyzer/SKILL.md

@@ -5,42 +5,64 @@ description: Code intelligence for the analyzer area — symbols, dependencies,
 
 # Analyzer
 
+## Working with this area
+When working with code in **analyzer/**, follow these mandatory safety rules:
+
+### Before editing any symbol in this area:
+1. Call `mcp_milens_impact({target: "<symbol>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn** before proceeding
+3. Call `mcp_milens_context({name: "<symbol>", repo: "<workspaceRoot>"})` — see all callers/callees
+
+### Before committing changes in this area:
+1. Call `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify scope
+2. If unexpected files changed → **STOP and report**
+
+### Key tools for this area:
+| Task | Tool |
+|---|---|
+| Find all references | `mcp_milens_context` |
+| Check edit safety | `mcp_milens_edit_check` |
+| Text search across files | `mcp_milens_grep` |
+| See file symbols | `mcp_milens_get_file_symbols` |
+
 ## Overview
-Contains 79 symbols (21 exported) across 7 files.
+Contains 80 symbols (21 exported) across 7 files.
 
 ## Key Symbols
+- **`reviewPr`** [function] (src/analyzer/review.ts:101) — 7 refs
+- **`analyze`** [function] (src/analyzer/engine.ts:125) — 6 refs
 - **`resolveLinksWithStats`** [function] (src/analyzer/resolver.ts:35) — 5 refs
 - **`loadAliases`** [function] (src/analyzer/config.ts:10) — 4 refs
-- **`analyze`** [function] (src/analyzer/engine.ts:106) — 4 refs
+- **`enrichMetadata`** [function] (src/analyzer/enrich.ts:21) — 4 refs
+- **`ReviewResult`** [interface] (src/analyzer/review.ts:17) — 4 refs
 - **`scanFiles`** [function] (src/analyzer/scanner.ts:11) — 4 refs
 - **`resolveLinks`** [function] (src/analyzer/resolver.ts:30) — 3 refs
-- **`reviewPr`** [function] (src/analyzer/review.ts:101) — 3 refs
-- **`enrichMetadata`** [function] (src/analyzer/enrich.ts:21) — 2 refs
 - **`reviewSymbol`** [function] (src/analyzer/review.ts:167) — 2 refs
 - **`generateTestPlan`** [function] (src/analyzer/testplan.ts:104) — 2 refs
 - **`findCoverageGaps`** [function] (src/analyzer/testplan.ts:175) — 2 refs
+- **`analyzeTestImpact`** [function] (src/analyzer/testplan.ts:208) — 2 refs
 - **`ResolutionResult`** [interface] (src/analyzer/resolver.ts:22) — 1 refs
-- **`ReviewResult`** [interface] (src/analyzer/review.ts:17) — 1 refs
+- **`SymbolRisk`** [interface] (src/analyzer/review.ts:8) — 1 refs
 - **`RiskLevel`** [type] (src/analyzer/review.ts:6) — 1 refs
-- **`TestImpactResult`** [interface] (src/analyzer/testplan.ts:35) — 1 refs
-- **`SymbolRisk`** [interface] (src/analyzer/review.ts:8) — 0 refs
 
 ## Entry Points
-- **`find`** [function] — 19 incoming references
-- **`resolve`** [method] — 11 incoming references
-- **`resolveLinksWithStats`** [function] — 5 incoming references
-- **`loadAliases`** [function] — 4 incoming references
-- **`analyze`** [function] — 4 incoming references
+- **`find`** [function] — 22 incoming references
+- **`resolve`** [method] — 16 incoming references
+- **`reviewPr`** [function] — 7 incoming references
+- **`analyze`** [function] — 6 incoming references
+- **`clear`** [method] — 5 incoming references
 
 ## Dependencies
-- **parser**: `langForFile`, `getParser`, `loadLanguage`, `extractFromTree`, `clearQueryCache`, `extractVueScript`, `extractVueTemplateRefs`, `extractHtmlScripts` (+6 more)
+- **parser**: `langForFile`, `supportedExtensions`, `getParser`, `loadLanguage`, `extractFromTree`, `clearQueryCache`, `extractVueScript`, `extractVueTemplateRefs` (+6 more)
 - **root**: `isTestFile`, `CodeSymbol`, `ExtractionResult`, `RawImport`, `RawCall`, `RawHeritage`, `RawReExport`, `RawTypeBinding` (+8 more)
-- **store**: `Database`, `TfIdfProvider`, `EmbeddingStore`, `buildEmbeddingText`, `get`, `clear`, `isFileUpToDate`, `upsertFileHash` (+22 more)
+- **store**: `Database`, `TfIdfProvider`, `EmbeddingStore`, `buildEmbeddingText`, `get`, `clearFiles`, `clear`, `isFileUpToDate` (+23 more)
+- **test**: `parser`, `lang`
 
 ## Used By
 - **root**: `loadAliases`, `analyze`, `resolve`, `clear`
-- **server**: `reviewPr`, `resolve`, `find`
-- **test**: `resolveLinks`, `resolveLinksWithStats`, `reviewSymbol`, `scanFiles`, `generateTestPlan`, `findCoverageGaps`, `analyze`, `loadAliases` (+1 more)
+- **orchestrator**: `reviewPr`, `ReviewResult`, `SymbolRisk`
+- **server**: `reviewPr`, `analyze`, `resolve`, `find`, `clear`
+- **test**: `enrichMetadata`, `resolveLinks`, `resolveLinksWithStats`, `reviewSymbol`, `reviewPr`, `scanFiles`, `generateTestPlan`, `findCoverageGaps` (+5 more)
 - **scripts**: `resolve`
 - **parser**: `find`, `resolve`
 - **store**: `find`, `resolve`

package/.agents/skills/apps/SKILL.md

@@ -5,8 +5,28 @@ description: Code intelligence for the apps area — symbols, dependencies, and
 
 # Apps
 
+## Working with this area
+When working with code in **apps/**, follow these mandatory safety rules:
+
+### Before editing any symbol in this area:
+1. Call `mcp_milens_impact({target: "<symbol>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn** before proceeding
+3. Call `mcp_milens_context({name: "<symbol>", repo: "<workspaceRoot>"})` — see all callers/callees
+
+### Before committing changes in this area:
+1. Call `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify scope
+2. If unexpected files changed → **STOP and report**
+
+### Key tools for this area:
+| Task | Tool |
+|---|---|
+| Find all references | `mcp_milens_context` |
+| Check edit safety | `mcp_milens_edit_check` |
+| Text search across files | `mcp_milens_grep` |
+| See file symbols | `mcp_milens_get_file_symbols` |
+
 ## Overview
-Contains 34 symbols (12 exported) across 10 files.
+Contains 38 symbols (12 exported) across 10 files.
 
 ## Key Symbols
 - **`Milens Desktop Dashboard`** [section] (apps/dashboard/README.md:1) — 0 refs
@@ -25,9 +45,13 @@ Contains 34 symbols (12 exported) across 10 files.
 ## Entry Points
 - **`createWindow`** [function] — 1 incoming references
 - **`__dirname`** [variable] — 1 incoming references
+- **`checkRateLimit`** [function] — 1 incoming references
+- **`getTier`** [function] — 1 incoming references
+- **`runMilensAnalyze`** [function] — 1 incoming references
 
 ## Dependencies
 - **store**: `remove`, `Database`, `getCodebaseSummary`, `close`
+- **test**: `dbPath`
 
 ## Files
 - apps/dashboard/README.md

package/.agents/skills/docs/SKILL.md

@@ -5,8 +5,28 @@ description: Code intelligence for the docs area — symbols, dependencies, and
 
 # Docs
 
+## Working with this area
+When working with code in **docs/**, follow these mandatory safety rules:
+
+### Before editing any symbol in this area:
+1. Call `mcp_milens_impact({target: "<symbol>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn** before proceeding
+3. Call `mcp_milens_context({name: "<symbol>", repo: "<workspaceRoot>"})` — see all callers/callees
+
+### Before committing changes in this area:
+1. Call `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify scope
+2. If unexpected files changed → **STOP and report**
+
+### Key tools for this area:
+| Task | Tool |
+|---|---|
+| Find all references | `mcp_milens_context` |
+| Check edit safety | `mcp_milens_edit_check` |
+| Text search across files | `mcp_milens_grep` |
+| See file symbols | `mcp_milens_get_file_symbols` |
+
 ## Overview
-Contains 266 symbols (253 exported) across 12 files.
+Contains 140 symbols (119 exported) across 19 files.
 
 ## Key Symbols
 - **`Adapter Packs`** [section] (docs/adapters.md:1) — 0 refs
@@ -22,25 +42,33 @@ Contains 266 symbols (253 exported) across 12 files.
 - **`Automated Install`** [section] (docs/adapters.md:66) — 0 refs
 - **`Profile Selection`** [section] (docs/adapters.md:74) — 0 refs
 - **`MCP Config Reference`** [section] (docs/adapters.md:86) — 0 refs
-- **`Hệ thống Khép kín Tuần hoàn cho AI-Driven Development`** [section] (docs/closed-loop-ai-development.md:1) — 0 refs
-- **`Mục lục`** [section] (docs/closed-loop-ai-development.md:9) — 0 refs
+- **`Upgrading Milens`** [section] (docs/milens-upgrade.md:1) — 0 refs
+- **`Storage Map`** [section] (docs/milens-upgrade.md:5) — 0 refs
 
 ## Entry Points
 - **`applyFilters`** [function] — 1 incoming references
+- **`applyFilters`** [function] — 1 incoming references
 
 ## Dependencies
 - **store**: `remove`
 
 ## Files
 - docs/README.md
+- docs/adapters.html
 - docs/adapters.md
-- docs/closed-loop-ai-development.md
-- docs/ecc-milens-vibe-code.md
+- docs/changelog.html
+- docs/compare.html
+- docs/github-app.html
 - docs/index.html
+- docs/learning.html
+- docs/milens-upgrade.md
+- docs/platforms.html
 - docs/pricing.html
 - docs/pricing.md
 - docs/quickstart.md
+- docs/scenarios.html
 - docs/security-presets.md
 - docs/security.html
 - docs/skills.html
 - docs/tools.md
+- docs/vi-VN/README.md

package/.agents/skills/milens/SKILL.md

@@ -4,9 +4,9 @@ description: Code intelligence MCP tools — symbol search, text grep, impact an
 ---
 
 <!-- milens:start -->
-# Milens — Code Intelligence (MCP)
+# Milens — AI-DOS
 
-This project is indexed by milens (1137 symbols, 1592 links, 104 files).
+The Operating System for AI-Driven Development. This project is indexed by milens (1078 symbols, 1822 links, 131 files).
 
 > **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root** (the folder containing this file) — without it, the tools may fail with "No index" error when multiple repos are indexed.
 
@@ -77,6 +77,17 @@ When the user says... → do this FIRST:
 | "start new session" | `mcp_milens_session_start({agent: "...", repo: "<workspaceRoot>"})` |
 | "find code like `X`" | `mcp_milens_find_similar({name: "X", repo: "<workspaceRoot>"})` |
 | "search for `concept`" | `mcp_milens_semantic_search({query: "concept", repo: "<workspaceRoot>"})` |
+| "generate tests for `X`" | `mcp_milens_test_generate({symbol: "X", repo: "<workspaceRoot>"})` |
+| "fix security issue in `X`" | `mcp_milens_fix_apply({ruleId, file, line, repo: "<workspaceRoot>"})` |
+| "remove dead code" | `mcp_milens_find_dead_code()` then `dead_code_remove` prompt |
+| "orchestrate/check changes" | `mcp_milens_orchestrate({repo: "<workspaceRoot>"})` |
+| "compare impact of `X`" | `mcp_milens_compare_impact({name: "X", action: "snapshot"|"compare", repo: "<workspaceRoot>"})` |
+| "check pre-commit" | `mcp_milens_pre_commit_check({repo: "<workspaceRoot>"})` |
+| "save/restore context" | `mcp_milens_hook_preCompact()` / `mcp_milens_hook_postCompact()` |
+| "scan security / audit security" | `mcp_milens_security_scan({repo: "<workspaceRoot>"})` — full audit across all 50+ rules |
+| "end session" / "finish work" | `mcp_milens_session_end({session_id: "..."})` — record stats, trigger onSessionEnd hook |
+| "what did session X do" | `mcp_milens_session_context({session_id: "..."})` — get annotations + tool calls |
+| "file changed to X" | `mcp_milens_hook_onFileChange({files: ["path/to/file"], repo: "<workspaceRoot>"})` |
 
 ## Documentation Workflows
 
@@ -120,16 +131,16 @@ Milens indexes **Markdown files** (.md, .mdx) — headings become `section` symb
 | `mcp_milens_get_file_symbols` | All symbols in a file |
 | `mcp_milens_get_type_hierarchy` | Class inheritance tree |
 | `mcp_milens_find_dead_code` | Unused exported symbols |
-| `mcp_milens_status` | Index health check |
+| `mcp_milens_status` | Index stats for a repository: symbols, links, files, coverage %, staleness |
 | `mcp_milens_edit_check` | Pre-edit safety: callers + export status + re-export chains + test coverage |
 | `mcp_milens_trace` | Execution flow: call chains from entrypoints to a symbol |
 | `mcp_milens_routes` | Detect framework routes/endpoints (Express, FastAPI, NestJS, etc.) |
 | `mcp_milens_smart_context` | Intent-aware context: understand/edit/debug/test |
-| `mcp_milens_overview` | Combined context + impact + grep in one call |
+| `mcp_milens_overview` | Combined context + impact + grep in ONE call. Preferred before editing/deleting/renaming a symbol. |
 | `mcp_milens_domains` | Domain clusters: groups of files forming logical modules |
 | `mcp_milens_repos` | List all indexed repositories with summary stats |
 | `mcp_milens_ast_explore` | Explore raw AST structure of a code file |
-| `mcp_milens_test_query` | Run raw SQL query against the milens index database |
+| `mcp_milens_test_query` | Run a tree-sitter query against a code snippet and return matched nodes with capture names |
 | `mcp_milens_review_pr` | PR risk assessment: scores changed symbols by blast radius + test coverage |
 | `mcp_milens_review_symbol` | Single symbol risk: role, heat, dependents, test status |
 | `mcp_milens_test_plan` | Dependency-aware test plan: mocks, strategies, suggested tests |
@@ -143,10 +154,20 @@ Milens indexes **Markdown files** (.md, .mdx) — headings become `section` symb
 | `mcp_milens_codebase_summary` | High-level bootstrapping context: domains, key symbols, coverage |
 | `mcp_milens_semantic_search` | Hybrid FTS5 + vector search (requires --embeddings) |
 | `mcp_milens_find_similar` | Find symbols similar by embedding proximity |
+| `mcp_milens_compare_impact` | Compare impact graph before/after edit — detects regressions |
+| `mcp_milens_orchestrate` | Run full orchestration cycle: detect_changes → review_pr → impact → coverage gaps → dead code → action plan |
+| `mcp_milens_fix_apply` | Apply a security fix to a file (creates backup) |
+| `mcp_milens_test_generate` | Auto-generate test file: detects framework (vitest/jest/mocha/pytest) and writes complete test with mock strategy |
+| `mcp_milens_pre_commit_check` | Pre-commit risk scan: review_pr + dead code + coverage gaps |
+| `mcp_milens_hook_preCompact` | Save metrics snapshot before context compaction |
+| `mcp_milens_hook_postCompact` | Restore context by recalling annotations after compaction |
+| `mcp_milens_session_end` | End a session and record its stats. Use at the end of every session. |
+| `mcp_milens_hook_onFileChange` | Trigger the onFileChange hook. Call when files are modified to get impact summary. |
+| `mcp_milens_security_scan` | Scan codebase for security vulnerabilities using 50+ built-in rules. Replaces multiple manual grep() calls. |
 
 ### Keeping the Index Fresh
 
-After significant code changes: `npx milens analyze -p . --force`
+After significant code changes: `npx milens analyze -p . --force` (replace `.` with your project root if running from a different directory)
 
 ### Skills
 
@@ -160,9 +181,18 @@ After significant code changes: `npx milens analyze -p . --force`
 | Work in the Test area | `.agents/skills/test/SKILL.md` |
 | Work in the Scripts area | `.agents/skills/scripts/SKILL.md` |
 | Work in the Analyzer area | `.agents/skills/analyzer/SKILL.md` |
+| Work in the Orchestrator area | `.agents/skills/orchestrator/SKILL.md` |
 | Work in the Parser area | `.agents/skills/parser/SKILL.md` |
 | Work in the Security area | `.agents/skills/security/SKILL.md` |
 | Work in the Server area | `.agents/skills/server/SKILL.md` |
 | Work in the Store area | `.agents/skills/store/SKILL.md` |
+| Execute milens-plan workflow | `.agents/skills/milens-plan/SKILL.md` |
+| Execute milens-code-review workflow | `.agents/skills/milens-code-review/SKILL.md` |
+| Execute milens-tdd workflow | `.agents/skills/milens-tdd/SKILL.md` |
+| Execute milens-security-review workflow | `.agents/skills/milens-security-review/SKILL.md` |
+| Execute milens-refactor-clean workflow | `.agents/skills/milens-refactor-clean/SKILL.md` |
+| Execute milens-eval workflow | `.agents/skills/milens-eval/SKILL.md` |
+| Execute milens-architect workflow | `.agents/skills/milens-architect/SKILL.md` |
+| Execute milens-debugger workflow | `.agents/skills/milens-debugger/SKILL.md` |
 
 <!-- milens:end -->

package/.agents/skills/milens-architect/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: milens-architect
+description: Architecture Analysis — domains, routes, coupling, class hierarchy, and refactoring suggestions with scorecard
+---
+
+# milens-architect — Architecture Analysis
+
+Analyze the architecture of the codebase: domain clusters, API routes, execution traces, class hierarchies, coupling hotspots, and produce a structured scorecard with refactoring suggestions.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_codebase_summary` | High-level project overview |
+| `mcp_milens_domains` | Module clusters with cohesion scores |
+| `mcp_milens_routes` | API endpoints inventory |
+| `mcp_milens_get_type_hierarchy` | Class/interface inheritance trees |
+| `mcp_milens_trace` | Execution flow from entrypoints |
+| `mcp_milens_explain_relationship` | Shortest path between two symbols |
+| `mcp_milens_find_dead_code` | Unused exported symbols |
+| `mcp_milens_review_symbol` | Deep-dive single symbol risk |
+| `mcp_milens_impact` | Blast radius analysis |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Codebase Overview
+
+Get a high-level picture of the codebase structure.
+
+```
+mcp_milens_codebase_summary({repo: "<workspaceRoot>"})
+```
+
+### Step 2: Domain Map
+
+Identify logical module groupings and cohesion.
+
+```
+mcp_milens_domains({repo: "<workspaceRoot>"})
+```
+
+For each domain with > 5 files, note: file count, symbol count, and description.
+
+### Step 3: Route Inventory
+
+Map all API endpoints to handler functions.
+
+```
+mcp_milens_routes({repo: "<workspaceRoot>"})
+```
+
+Document: HTTP method, path, handler symbol, and domain.
+
+### Step 4: Class Hierarchy
+
+For each key class/interface in the codebase, trace inheritance chains.
+
+```
+mcp_milens_get_type_hierarchy({name: "<BaseClass>", repo: "<workspaceRoot>"})
+```
+
+### Step 5: Execution Traces
+
+Trace critical execution paths from entrypoints.
+
+```
+mcp_milens_trace({name: "<entrypoint>", direction: "from", repo: "<workspaceRoot>"})
+```
+
+### Step 6: Coupling Analysis
+
+For the top 5 hub symbols, analyze inter-domain coupling:
+
+```
+mcp_milens_impact({target: "<hubSymbol>", depth: 3, repo: "<workspaceRoot>"})
+```
+
+```
+mcp_milens_explain_relationship({from: "<domain-a>", to: "<domain-b>", repo: "<workspaceRoot>"})
+```
+
+### Step 7: Dead Code Detection
+
+Find unused symbols that may indicate architectural drift.
+
+```
+mcp_milens_find_dead_code({limit: 30, repo: "<workspaceRoot>"})
+```
+
+### Step 8: Architecture Scorecard
+
+Produce a structured scorecard:
+
+| Dimension | Score (1-10) | Notes |
+|---|---|---|
+| Domain Cohesion | | |
+| Inter-domain Coupling | | |
+| Route Coverage | | |
+| Entry Point Clarity | | |
+| Inheritance Depth | | |
+| Dead Code Ratio | | |
+
+List top 3 refactoring suggestions with risk levels and effort estimates.
+
+## Quality Gate
+
+### PASS if:
+- [x] All domains documented with file/symbol counts
+- [x] All API routes mapped to handlers
+- [x] At least 5 class hierarchies traced
+- [x] At least 3 execution traces analyzed
+- [x] Coupling hotspots identified
+- [x] Architecture scorecard completed with scores
+- [x] Top 3 refactoring suggestions documented with risk levels
+
+### FAIL if:
+- [ ] Any step skipped without documented reason
+- [ ] Scorecard incomplete or scored without evidence
+- [ ] Refactoring suggestions lack risk assessment
+
+## Never Skip
+
+1. Always run `mcp_milens_codebase_summary` first — it provides the scaffolding for all other steps
+2. Never skip coupling analysis — it's the most critical architecture insight
+3. Always include risk levels and effort estimates in refactoring suggestions
+4. Cross-reference findings with `mcp_milens_review_symbol` for CRITICAL hubs

package/.agents/skills/milens-debugger/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: milens-debugger
+description: Root Cause Analysis — execution trace, blast radius, dependency paths, deep context, and ranked hypotheses with fix suggestions
+---
+
+# milens-debugger — Root Cause Analysis
+
+Debug issues by tracing execution flow, analyzing blast radius, exploring dependency paths, and producing ranked root cause hypotheses with fix suggestions and regression risk assessment.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_trace` | Execution flow from entrypoints to target (or reverse) |
+| `mcp_milens_context` | 360° symbol view: incoming refs + outgoing deps |
+| `mcp_milens_impact` | Blast radius: what breaks if target changes |
+| `mcp_milens_explain_relationship` | Shortest path between two symbols |
+| `mcp_milens_smart_context` | Intent-aware context for debug intent |
+| `mcp_milens_overview` | Combined context + impact + grep in one call |
+| `mcp_milens_grep` | Text search across all files (templates, configs, error messages) |
+| `mcp_milens_review_symbol` | Deep-dive single symbol risk assessment |
+| `mcp_milens_get_type_hierarchy` | Class inheritance chain |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: Understand the Target
+
+Get deep context on the problematic symbol.
+
+```
+mcp_milens_smart_context({name: "<targetSymbol>", intent: "debug", repo: "<workspaceRoot>"})
+```
+
+This returns execution paths, data flow, dependencies, and test coverage in one call.
+
+### Step 2: Trace Execution
+
+Map how code reaches the target from entrypoints.
+
+```
+mcp_milens_trace({name: "<targetSymbol>", direction: "to", repo: "<workspaceRoot>"})
+```
+
+For downstream impact, trace forward:
+
+```
+mcp_milens_trace({name: "<targetSymbol>", direction: "from", repo: "<workspaceRoot>"})
+```
+
+### Step 3: Blast Radius
+
+Understand what breaks if the target is modified.
+
+```
+mcp_milens_impact({target: "<targetSymbol>", depth: 3, repo: "<workspaceRoot>"})
+```
+
+Pay special attention to depth-1 dependents — these WILL break.
+
+### Step 4: Dependency Paths
+
+For each suspect dependency, trace the exact connection path.
+
+```
+mcp_milens_explain_relationship({from: "<suspect>", to: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+### Step 5: Full Context View
+
+Get a 360° view of the target and its immediate neighbors.
+
+```
+mcp_milens_context({name: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+Check both incoming (who calls this) and outgoing (what this calls).
+
+### Step 6: Text Search for Clues
+
+Search for error messages, TODOs, or related patterns.
+
+```
+mcp_milens_grep({pattern: "<errorMessage or keyword>", repo: "<workspaceRoot>"})
+```
+
+Use `include` to narrow scope (e.g., `"**/*.ts"`, `"**/*.md"`).
+
+### Step 7: Class Hierarchy
+
+If the target is a class, check its inheritance chain.
+
+```
+mcp_milens_get_type_hierarchy({name: "<ClassName>", repo: "<workspaceRoot>"})
+```
+
+### Step 8: Risk Assessment
+
+Deep-dive the target's risk profile.
+
+```
+mcp_milens_review_symbol({name: "<targetSymbol>", repo: "<workspaceRoot>"})
+```
+
+### Step 9: Root Cause Hypotheses
+
+Rank hypotheses by likelihood:
+
+| # | Hypothesis | Evidence | Confidence | Suggested Fix | Regression Risk |
+|---|---|---|---|---|---|
+| 1 | | | HIGH/MEDIUM/LOW | | |
+| 2 | | | | | |
+| 3 | | | | | |
+
+Each hypothesis MUST cite specific tools and their output as evidence.
+
+## Quality Gate
+
+### PASS if:
+- [x] Execution trace complete (both directions)
+- [x] Blast radius analyzed to depth 3
+- [x] At least 3 dependency paths traced
+- [x] Full 360° context captured
+- [x] Text search performed for error messages/keywords
+- [x] At least 3 ranked hypotheses with evidence citations
+- [x] Fix suggestions include regression risk assessment
+
+### FAIL if:
+- [ ] Any step skipped without documented reason
+- [ ] Hypotheses lack tool evidence citations
+- [ ] Fix suggestions have no regression risk assessment
+- [ ] Only one hypothesis considered (lack of thoroughness)
+
+## Never Skip
+
+1. Always run `mcp_milens_smart_context` first — it is the most efficient starting point for debugging
+2. Never skip blast radius analysis — a fix that introduces new breakage is not a fix
+3. Always cite specific tool outputs as evidence for each hypothesis
+4. Always include regression risk in fix suggestions
+5. If dead code is suspected, run `mcp_milens_find_dead_code` to check for unused symbols in the trace path

package/.agents/skills/orchestrator/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: milens-orchestrator
+description: Code intelligence for the orchestrator area — symbols, dependencies, and entry points
+---
+
+# Orchestrator
+
+## Working with this area
+When working with code in **orchestrator/**, follow these mandatory safety rules:
+
+### Before editing any symbol in this area:
+1. Call `mcp_milens_impact({target: "<symbol>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn** before proceeding
+3. Call `mcp_milens_context({name: "<symbol>", repo: "<workspaceRoot>"})` — see all callers/callees
+
+### Before committing changes in this area:
+1. Call `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify scope
+2. If unexpected files changed → **STOP and report**
+
+### Key tools for this area:
+| Task | Tool |
+|---|---|
+| Find all references | `mcp_milens_context` |
+| Check edit safety | `mcp_milens_edit_check` |
+| Text search across files | `mcp_milens_grep` |
+| See file symbols | `mcp_milens_get_file_symbols` |
+
+## Overview
+Contains 22 symbols (7 exported) across 2 files.
+
+## Key Symbols
+- **`Orchestrator`** [class] (src/orchestrator/orchestrator.ts:36) — 6 refs
+- **`OrchestratorReport`** [interface] (src/orchestrator/reporter.ts:4) — 5 refs
+- **`formatReport`** [function] (src/orchestrator/reporter.ts:17) — 4 refs
+- **`OrchestratorConfig`** [interface] (src/orchestrator/orchestrator.ts:10) — 2 refs
+- **`ImpactSnapshot`** [interface] (src/orchestrator/orchestrator.ts:18) — 2 refs
+- **`ReportOptions`** [interface] (src/orchestrator/reporter.ts:13) — 2 refs
+- **`ImpactDiff`** [interface] (src/orchestrator/orchestrator.ts:25) — 1 refs
+
+## Entry Points
+- **`Orchestrator`** [class] — 6 incoming references
+- **`OrchestratorReport`** [interface] — 5 incoming references
+- **`formatReport`** [function] — 4 incoming references
+- **`snapshot`** [method] — 3 incoming references
+- **`run`** [method] — 3 incoming references
+
+## Dependencies
+- **store**: `Database`, `findSymbolByName`, `findUpstream`, `clear`, `getTestCoverageGaps`, `findDeadCode`, `close`
+- **analyzer**: `reviewPr`, `ReviewResult`, `SymbolRisk`
+- **root**: `CodeSymbol`, `has`
+
+## Used By
+- **root**: `Orchestrator`, `subscribe`, `runAndFormat`
+- **server**: `Orchestrator`, `snapshot`, `compare`, `runAndFormat`
+- **test**: `Orchestrator`, `formatReport`, `OrchestratorReport`, `subscribe`, `run`, `snapshot`, `compare`, `cancel` (+3 more)
+
+## Files
+- src/orchestrator/orchestrator.ts
+- src/orchestrator/reporter.ts