navigation-mcp

Files (2)

• SKILL.md
• full-contract.md · references/

SKILL.md (first lines)

## Activation Contract

Use this skill for workspace-only code discovery: locating files, symbols, routes, endpoints, text matches, caller impact, or downstream flow before editing.

Do not use it for web search, external repositories, parent directories, arbitrary filesystem access, or reading full file contents.

## Hard Rules

1. If discovery is needed, use navigation first; do not open multiple files cold.
2. If the exact file is already known and no discovery is needed, `read` is allowed.
3. Canonical tools are `code.inspect_tree`, `code.find_symbol`, `code.list_endpoints`, `code.search_text`, `code.trace_flow`, and `code.trace_callers`.
4. Clients may expose aliases such as `navigation-agent_code_find_symbol`; use the available alias but preserve canonical `code.*` semantics.
5. Supported language filters: `typescript`, `javascript`, `go`, `java`, `php`, `python`, `rust`, `csharp`.
6. Supported framework filters: `react-router`, `spring`.
7. Use `snake_case` parameters: `max_depth`, `include_hidden`, `file_pattern`, `recursive`.
8. Treat navigation output as a scope reducer, not file content. Read only returned files that matter.
9. Use `glob`, `bash grep`, or `bash find` only when navigation is unavailable, unsupported, or returned no useful result after narrowing.
10. Do not use text search when a symbol trace would answer better.
11. Do not call `trace_flow` to find callers or `trace_callers` to follow behavior.
12. Do not treat a zero-result navigation response as proof without a scoped fallback.

## Decision Gates

| Need | Use first | Then |
| --- | --- | --- |
| Understand an unknown module | `code.inspect_tree` | Read selected paths only |
| Find a class/function/method/type | `code.find_symbol` | Trace or read returned path |
| Audit REST/GraphQL/routes | `code.list_endpoints` | Trace or read entrypoints |
| Find imports/decorators/text | `code.search_text` | Prioritize `topFiles`, then read |
| Know what a symbol calls | `code.find_symbol` | `code.trace_flow` with `items[].path` |
| Know who calls a symbol | `code.find_symbol` | `code.trace_callers` with `recursive: true` for shared APIs |

## Execution Steps

1. Identify the narrowest known scope: `path`, `language`, and `framework` when available.
2. Start with the most specific navigation tool from the decision table.
3. Chain tool outputs: pass `find_symbol.items[].path` as `path` to `trace_flow` or `trace_callers`.
4. Remember direction: `trace_flow` is downstream behavior; `trace_callers` is upstream impact.
5. If `find_symbol` misses constants, config keys, decorators, imports, or generated names, use `code.search_text` scoped by `path`, `include`, and `language`.
6. If trace output is too broad, narrow `path`, `language`, `framework`, or `symbol`; for `trace_callers`, lower `max_depth`.
7. If endpoint discovery returns zero, retry with narrower `path` and the most specific `framework` or `kind` before concluding there is no public surface.
8. If results are empty or `truncated: true`, narrow before reading files or increasing `limit`.
9. Read only the small set of files needed to answer or edit safely.

## Output Contract

Return:
- Navigation path used and why.
- Important resolved files, symbols, endpoints, or callers.
- Any fallback used after navigation failed or was unsupported.
- Limitations such as unsupported framework detection, truncation, or zero endpoint results.
- Files that still need direct `read` before editing.

## References

- `README.md` — public contract, compatibility matrix, and agent usage guide.

From j0k3r-dev-rgl/open-code-config-public, Apache-2.0.

More from j0k3r-dev-rgl/open-code-config-public