Code Ontology Companion

View saved version →

---
name: manage-code-ontology
description: Map authorized Java/Spring or Python code structure, locate symbols and static dependency paths, compare ontology snapshots, or explore an offline 3D code map. Provides source evidence, not runtime traces. Does not manage general project memories or validate arbitrary contracts.
---

# Manage Code Ontology

[English](SKILL.md) | [한국어](https://github.com/battle-doll/code-ontology-companion/blob/main/docs/ko/SKILL_GUIDE.md) | [日本語](https://github.com/battle-doll/code-ontology-companion/blob/main/docs/ja/SKILL_GUIDE.md) | [简体中文](https://github.com/battle-doll/code-ontology-companion/blob/main/docs/zh-CN/SKILL_GUIDE.md)

Version 0.6.0 provides a human-facing 3D workbench and structured evidence for AI clients. Use it to reverse-engineer an existing authorized codebase without importing, building, testing, or running the target. Deterministic analysis and local MCP make no direct network requests.

## Resolve the trusted bundle

Resolve the installed directory containing this SKILL.md. Verify `scripts/companion.py`, `scripts/code_ontology_core.py`, `scripts/local_llm.py`, and `scripts/code_reference.py` are regular files inside that exact bundle. Use Python 3.9 or newer; on Windows use an existing `py -3` interpreter if needed. Never execute same-named helpers from the target repository. The examples below use `$COMPANION` for that verified absolute companion.py path and `$REFERENCE` for code_reference.py.

## Choose the shortest applicable workflow

- Existing workspace: list registered workspaces through available local MCP, then check status. Use its workspace ID; MCP does not accept arbitrary paths. If MCP is unavailable, use the bundled CLI with the selected workspace. Do not reinstall or reconfigure a working setup.
- New workspace: read [workspace-setup.md](references/workspace-setup.md). Run `doctor` and `preflight` first; summarize support and exclusions. Show a new workspace outside the target and disclose local symbol/path/line data, private absolute repository path and per-file SHA-256 manifest. Initialize after authorization, including authorization already explicit in the user's request.
- Local MCP configuration: read [local-mcp.md](references/local-mcp.md). The official skills-only bundle includes setup guidance; the complete GitHub package includes the local server. Do not invent a remote endpoint or silently add a duplicate server.
- Optional local inference: use only when the user requests it. Read [local-llm.md](references/local-llm.md) and the consent sequence in workspace-setup.md. No silent model selection, installation, download, service start, probe, or configuration. An ordinary structural query does not need a model.
- Code/Context interchange: read [code-reference.md](references/code-reference.md). Export selected references locally; retain immutable original evidence behind the locator. Contracts validation does not establish truth or current authorization. Do not store Context records or upload artifacts without the corresponding user request.

## Find and explain code

Check freshness with `status --workspace ...`. When the source is stale and a refresh is authorized, use `sync --workspace ...`; a no-write request takes precedence. Otherwise report the selected snapshot as stale and answer only within that snapshot. Pin related reads to the same returned snapshot ID when supported so concurrent refreshes cannot mix evidence.

Use exact symbol IDs or qualified names before broad substring terms. Narrow the language, kind, and relative module/path where supported, and request the smallest useful result range. A truncated result is not the complete result set. A missing match is not proof of absence when support is partial.

For impact, separate callers/dependents from dependencies. Follow actual dependency paths; shared framework labels alone do not establish change propagation. Cite the path and each material relationship's `rule_id`, `basis`, source span, `r

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 24 — file references are metadata, not package contents.