Instruction file imported from fuze210699/milens (.github/instructions/milens.instructions.md). Copyright stays with the author.

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.

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:

Domain-aware skill triggers:

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:

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:

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

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)

🔧 Situational Tools — Use When Needed (15)

📚 Advanced Tools — Reference (20)

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