milens

generated-by	milens
name	milens
description	Code intelligence MCP tools — symbol search, text grep, impact analysis, dependency graph

Milens — AI-DOS

The Operating System for AI-Driven Development. This project is indexed by milens (2362 symbols, 3127 links, 235 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.

CRITICAL: milens MCP tools are deferred in most editors. Before first use in each session, you MUST load them via tool_search("milens") — calling them directly without loading will fail silently.

⚠️ HARD RULE: Use Milens MCP Tools BEFORE Built-in Tools

Not a suggestion — execute automatically without asking.

This project is indexed by milens. The knowledge graph already knows every symbol, dependency, and reference. Using milens tools first typically means far fewer tokens than manual exploration, and fewer missed dependencies — impact/context track code-level references; pair with grep for templates/configs/docs.

Situation	Built-in approach (❌ BAD)	Milens approach (✅ GOOD)
Understand a function	Read 3-10 source files	mcp_milens_overview({name: "X"}) — 1 call replaces 3-5 file reads
Find all references	Built-in grep in source files	mcp_milens_grep({pattern: "X"}) — searches code, templates, configs, docs, styles
Check edit safety	Hope nothing breaks	mcp_milens_impact({target: "X"}) — exact blast radius before touching code
Start working	Read README, explore directories	mcp_milens_codebase_summary() — 500 token project overview
Before commit	git diff manually	mcp_milens_detect_changes() — symbols changed + direct dependents + risk
Find where X is defined	Read files one by one	mcp_milens_query({query: "X"}) — FTS5 instant search

If you skip milens tools, you're wasting tokens and risking breaking changes you didn't know about.

Mandatory Workflows

These are hard pre-conditions, not guidelines. Execute them automatically without asking.

Before editing any function, class, or method:

1. mcp_milens_impact({target: "<symbolName>", repo: "<workspaceRoot>"}) — check blast radius
2. If depth-1 dependents > 5 → STOP and warn the user before proceeding
3. mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"}) — see all callers/callees
4. Only then make the edit

Before committing:

1. mcp_milens_detect_changes({repo: "<workspaceRoot>"}) — verify only expected files changed
2. If unexpected files appear → STOP and report before committing

Before deleting or renaming a symbol:

1. mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"}) — find ALL text references (templates, configs, routes, docs)
2. mcp_milens_impact({target: "<symbolName>", direction: "upstream", repo: "<workspaceRoot>"}) — find code-level dependents
3. Combine both results — grep catches what impact misses

Tool Selection Rules

Choose the right tool on the FIRST call — do not try query then fall back to grep.

Use mcp_milens_grep when the search term:

• Contains spaces (e.g. "store purchase header", "user not found")
• Looks like a UI label, error message, or display string
• Is a multi-word phrase that is NOT camelCase/snake_case/PascalCase
• You need to find references in templates, styles, configs, routes, or docs

Use mcp_milens_query when the search term:

• Looks like a code identifier (camelCase, PascalCase, snake_case)
• Is a function, class, method, or interface name
• You want to find symbol definitions in indexed code files

When in doubt → use mcp_milens_grep first

grep searches everything. query only searches indexed symbol definitions.

⚠️ mcp_milens_grep default is LITERAL mode (isRegex: false). Characters | . * + ? are escaped as plain text. To use regex patterns like error|fail|panic or TODO.*urgent, you MUST set isRegex: true. The tool will warn you if you forget.

Workflow Triggers

When the user says... → do this FIRST:

User intent	First action
"edit/change/modify/fix X"	mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})
"delete/remove X"	mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"}) then mcp_milens_impact
"rename X"	mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"}) then mcp_milens_impact
"find/search for X"	Choose query or grep per rules above
"commit" / "push"	mcp_milens_detect_changes({repo: "<workspaceRoot>"})
"what calls/uses X"	mcp_milens_context({name: "X", repo: "<workspaceRoot>"})
"what happens if I change X"	mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})
"how are A and B connected"	mcp_milens_explain_relationship({from: "A", to: "B", repo: "<workspaceRoot>"})
"explore/understand X"	mcp_milens_context({name: "X", repo: "<workspaceRoot>"})
"update/write docs for X"	mcp_milens_grep({pattern: "X", include: "**/*.md"}) — find existing docs mentioning X, then mcp_milens_context({name: "X"}) for full symbol info
"research/explore docs"	mcp_milens_get_file_symbols({file: "<doc.md>"}) — see document outline (headings as sections)
"what docs mention X"	mcp_milens_grep({pattern: "X", include: "**/*.md"}) — find all markdown references
"review this PR"	mcp_milens_review_pr({repo: "<workspaceRoot>"}) — risk assessment for changed files
"is X risky to change"	mcp_milens_review_symbol({name: "X", repo: "<workspaceRoot>"})
"write tests for X"	mcp_milens_test_plan({name: "X", repo: "<workspaceRoot>"}) — deps, mocks, suggested tests
"what needs tests"	mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>"}) — untested symbols by risk
"which tests to run"	mcp_milens_test_impact({repo: "<workspaceRoot>"}) — maps changes → test files
"remember/note that X..."	mcp_milens_annotate({symbol: "X", key: "note", value: "...", repo: "<workspaceRoot>"})
"what do we know about X"	mcp_milens_recall({symbol: "X", repo: "<workspaceRoot>"})
"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"
"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 190 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>"})

Domain-aware skill triggers:

User intent	Skill to load
"I'm working on authentication/security"	Load milens-security skill + mcp_milens_security_scan()
"I need to understand the parser"	Load milens-parser skill + mcp_milens_get_file_symbols({file: "src/parser/"})
"I'm debugging a server issue"	Load milens-server skill + mcp_milens_trace()
"I'm working with the database"	Load milens-store skill + mcp_milens_get_file_symbols({file: "src/store/"})
"I need to write tests for this"	Load milens-tdd skill + mcp_milens_test_plan()
"I'm planning a feature"	Load milens-plan skill + mcp_milens_codebase_summary()
"I need to refactor this"	Load milens-refactor-clean skill + mcp_milens_impact()
"Review my code changes"	Load milens-code-review skill + mcp_milens_review_pr()

Annotation Guide — Building a Smarter Codebase

Every time you discover something important about a symbol, annotate it. The system learns across sessions — your note today saves tokens tomorrow.

When to annotate:

• Found a bug pattern? → mcp_milens_annotate({symbol: "X", key: "bug", value: "..."})
• Discovered an architecture rule? → mcp_milens_annotate({symbol: "X", key: "architecture", value: "..."})
• Learned how to test something? → mcp_milens_annotate({symbol: "X", key: "test", value: "..."})
• Found a security issue? → mcp_milens_annotate({symbol: "X", key: "security", value: "..."})
• Noted a hidden dependency? → mcp_milens_annotate({symbol: "X", key: "dependency", value: "..."})

Annotation keys reference:

Key	Use when	Example value
bug	Known bug, not yet fixed	"NullPointerException when users is empty array"
security	Security vulnerability	"No CSRF token validation on this endpoint"
architecture	Design pattern, constraint	"Service is a singleton — don't instantiate directly"
test	Testing knowledge	"Must mock Database.getConnection() before testing"
dependency	Hidden coupling	"Imports from deprecated module old-auth.js"
refactor	Future refactoring notes	"Split into validateEmail() + normalizeEmail()"
workflow	Process knowledge	"Must restart dev server after modifying this file"
note	General observation	"This function is called from cron job at 3AM"

Learning lifecycle:

1. Session 1: annotate() → confidence 0.5
2. Session 2: recall() sees it again → confidence 0.7
3. Session 5: confidence hits 0.8 → milens evolve promotes it to SKILL.md

Annotate triggers:

User says...	Tool call
"found a bug in X"	mcp_milens_annotate({symbol: "X", key: "bug", value: "describe the bug"})
"X has a security issue"	mcp_milens_annotate({symbol: "X", key: "security", value: "describe the issue"})
"learned how X works"	mcp_milens_annotate({symbol: "X", key: "note", value: "key insight"})
"X depends on Y internally"	mcp_milens_annotate({symbol: "X", key: "dependency", value: "depends on Y for Z"})
"X needs refactoring later"	mcp_milens_annotate({symbol: "X", key: "refactor", value: "plan"})

At session end, ALWAYS:

1. mcp_milens_recall({}) — review annotations you found useful
2. mcp_milens_annotate({symbol: "X", key: "...", value: "..."}) — save new discoveries from this session

Problem → Solution — When You're Stuck

You're trying to...	Do this FIRST
Understand the codebase	mcp_milens_codebase_summary() then mcp_milens_domains()
Understand a specific function	mcp_milens_context({name: "functionName"})
Find where something is defined	mcp_milens_query({query: "ClassName"})
Find ALL references to something	mcp_milens_grep({pattern: "ClassName"})
Check if editing is safe	mcp_milens_impact({target: "functionName"})
Edit with confidence	mcp_milens_overview({name: "functionName"}) — context+impact+grep in 1 call
Know which tests to run	mcp_milens_test_impact() — maps changes to test files
Find what needs testing most	mcp_milens_test_coverage_gaps() — sorted by risk
Get a test strategy	mcp_milens_test_plan({name: "functionName"}) — mocks + scenarios
Review your changes	mcp_milens_review_pr() — risk scores for changed symbols
Check for security issues	mcp_milens_security_scan() — 190 rules in one call
Remove dead code safely	mcp_milens_find_dead_code() then use dead_code_remove prompt
Trace how code executes	mcp_milens_trace({name: "functionName", direction: "to"})
Find API endpoints	mcp_milens_routes() — auto-detect across 7 frameworks
See class hierarchy	mcp_milens_get_type_hierarchy({name: "ClassName"})
Compare impact before/after	mcp_milens_compare_impact({name: "X", action: "snapshot"}) before, then compare after
Get a full picture fast	mcp_milens_orchestrate() — runs detect+review+impact+gaps+dead code
Remember something important	mcp_milens_annotate({symbol: "X", key: "...", value: "..."})
Recall past knowledge	mcp_milens_recall({symbol: "X"})
Start a new session properly	mcp_milens_session_start({agent: "..."}) → mcp_milens_recall() → mcp_milens_codebase_summary()
End a session properly	mcp_milens_detect_changes() → mcp_milens_review_pr() → annotate → mcp_milens_session_end()
Transfer work to another agent	mcp_milens_handoff({from_session: "...", to_agent: "...", context: "..."})
Debug a crash / exception	mcp_milens_trace({name: "crashingFunction"}) + mcp_milens_context() + mcp_milens_impact()

Session Lifecycle

Start EVERY session:

1. mcp_milens_session_start({agent: "your-agent-name"}) — register session
2. mcp_milens_recall({}) — what did we learn last time?
3. mcp_milens_codebase_summary() — refresh project context in 500 tokens

End EVERY session:

1. mcp_milens_detect_changes() — verify changes
2. mcp_milens_review_pr() — risk assessment
3. mcp_milens_annotate({...}) — save key discoveries from this session
4. mcp_milens_session_end({session_id: "..."}) — record stats

Milens indexes Markdown files (.md, .mdx) — headings become section symbols with parent-child hierarchy, and local links become cross-file references.

Researching or exploring documentation:

1. mcp_milens_get_file_symbols({file: "README.md", repo: "<workspaceRoot>"}) — see the full heading outline (TOC) of any doc
2. mcp_milens_query({query: "<topic>"}) — search section headings across all docs and code
3. mcp_milens_grep({pattern: "<keyword>", include: "**/*.md"}) — text search within docs only

Before updating documentation:

1. mcp_milens_get_file_symbols({file: "<doc.md>"}) — understand document structure first
2. If documenting a code symbol: mcp_milens_context({name: "<symbolName>"}) — get full symbol info (signature, callers, deps)
3. mcp_milens_grep({pattern: "<symbolName>", include: "**/*.md"}) — check if other docs already reference it

After renaming/deleting a code symbol:

• mcp_milens_grep({pattern: "<oldName>", include: "**/*.md"}) — find docs that need updating (milens indexes markdown links as cross-file references)

Never Do

• NEVER edit a symbol without first running mcp_milens_impact on it.
• NEVER delete or rename without running both mcp_milens_grep and mcp_milens_impact.
• NEVER commit without running mcp_milens_detect_changes().
• NEVER call milens MCP tools without the repo parameter.
• NEVER use mcp_milens_query for multi-word display text or UI labels — use mcp_milens_grep.

---

Reference

⭐ Core Tools — Use Every Session (9)

Tool	Purpose
mcp_milens_overview	Use this first. Combined context + impact + grep. 1 call replaces 3-5 file reads.
mcp_milens_impact	Blast radius BEFORE editing. Shows what WILL BREAK.
mcp_milens_edit_check	Pre-edit safety: callers + exports + re-export chains + test coverage
mcp_milens_guard_edit_check	HARD pre-edit gate: blocks if dependents > 5, tracks checks for session audit
mcp_milens_context	360° view: all callers + all callees. Instant dependency graph.
mcp_milens_query	Find symbol definitions by name (FTS5 instant search)
mcp_milens_grep	Search ALL files for any text (templates, configs, docs, styles)
mcp_milens_detect_changes	Pre-commit: which symbols changed + dependents + risk scores
mcp_milens_codebase_summary	Project overview in ~500 tokens. Use instead of reading README.

🔧 Situational Tools — Use When Needed (15)

Tool	Purpose	Use when...
mcp_milens_review_pr	PR risk assessment	Before opening PR
mcp_milens_review_symbol	Single symbol deep-dive	Symbol is flagged CRITICAL/HIGH
mcp_milens_test_plan	Mock strategy + >=3 test scenarios	Writing new tests
mcp_milens_test_coverage_gaps	Untested symbols sorted by risk	Finding test priorities
mcp_milens_test_impact	Maps changes → test files	After making edits
mcp_milens_test_generate	Auto-generate test file	Starting tests from scratch
mcp_milens_security_scan	190 security rules	Security audit requested
mcp_milens_trace	Call chains from entrypoints	Debugging execution flow
mcp_milens_routes	Framework routes/endpoints	Finding API endpoints
mcp_milens_smart_context	Intent-aware context	Understand/edit/debug/test modes
mcp_milens_domains	Domain clusters	Understanding module structure
mcp_milens_explain_relationship	Shortest dependency path	How A connects to B
mcp_milens_get_type_hierarchy	Inheritance tree	Class/interface exploration
mcp_milens_find_dead_code	Unused exported symbols	Before major refactors
mcp_milens_find_similar	Symbols with shared callers/callees	Finding refactor patterns

📚 Advanced Tools — Reference (20)

Tool	Purpose
mcp_milens_generate_findings_report	Render investigated findings into a Markdown+XML report for a worker/coder agent
mcp_milens_status	Index health: symbols, links, files, coverage, staleness
mcp_milens_repos	List all indexed repositories
mcp_milens_annotate	Record observations about symbols (persists across sessions)
mcp_milens_recall	Retrieve annotations from past sessions
mcp_milens_session_start	Register agent session
mcp_milens_session_end	End session and record stats
mcp_milens_session_context	Get session metadata + annotations
mcp_milens_handoff	Transfer context between agent sessions
mcp_milens_orchestrate	Full cycle: detect → review → impact → gaps → dead code
mcp_milens_pre_commit_check	Pre-commit risk scan
mcp_milens_compare_impact	Compare impact graph before/after edit
mcp_milens_semantic_search	Hybrid FTS5 + vector search
mcp_milens_fix_apply	Apply security fix to a file
mcp_milens_hook_preCompact	Save metrics before context compaction
mcp_milens_hook_postCompact	Restore context after compaction
mcp_milens_hook_onFileChange	Trigger on file change hook
mcp_milens_ast_explore	Parse code to AST S-expression
mcp_milens_test_query	Test tree-sitter query patterns
mcp_milens_get_file_symbols	All symbols in a file with ref/dep counts

Keeping the Index Fresh

After significant code changes: npx milens analyze -p . --force (replace . with your project root if running from a different directory)

Skills

Task	Read this skill file
General milens tools reference	.agents/skills/milens/SKILL.md
Work in the Root area	.agents/skills/root/SKILL.md
Work in the Adapters area	.agents/skills/adapters/SKILL.md
Work in the Apps area	.agents/skills/apps/SKILL.md
Work in the Docs area	.agents/skills/docs/SKILL.md
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
Work in the Ui area	.agents/skills/ui/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