nexus-mapper

nexus-mapper — AI Project Probing Protocol

This Skill guides the AI Agent to use the PROBE five-stage protocolto perform systematic probing on any local Git repository and produce a .nexus-map/ layered knowledge base.

---

When to invoke / when not to invoke

Scenario	Invoke
The user provides a local repo path and wants the AI to understand its architecture	Yes
Need to generate .nexus-map/INDEX.md for cold start of subsequent AI sessions	Yes
The user says "help me analyze the project", "build a project knowledge base", "let the AI understand this repository"	Yes
The runtime environment has no shell execution capability (pure API call mode, no run_command tool)	No
The host machine has no local Python 3.10+	No
The target repository has no known language source files (.py/.ts/.java/.go/.rs/.cpp etc. are all absent)	No
The user only wants to query a specific file/function → directly use view_file / grep_search	No

---

Prerequisite checks

Missing items must be explicitly communicated to the user; when degradation etc. is needed, promptly remind the user, and continue only after consent.

Prerequisite	Check method
Target path exists	$repo_path accessible
Python 3.10+	python --version >= 3.10
Script dependencies installed	python -c "import tree_sitter" no errors
Has shell execution capability	Agent environment supports run_command tool invocation

git history is a bonus, not a hard blocker. When there is no .git or too little history, skip hotspot analysis, and clearly record in the output that this was a degraded probe.

---

Input contract

repo_path: 目标仓库的本地绝对路径（必填）

Language support: automatically dispatch by file extension; language configuration (extension mapping + Tree-sitter queries) is stored in scripts/languages.json. Currently integrated with 30+ languages including Python/JavaScript/TypeScript/TSX/Bash/Java/Go/Rust/C#/C/C++/Kotlin/Ruby/Swift/Scala/PHP/Lua/Elixir/GDScript/Dart/Haskell/Clojure/SQL/Proto/Solidity/Vue/Svelte/R/Perl.

Non-standard languages: if the repository contains languages not supported by built-ins, dynamically supplement them via command-line arguments (see references/05-language-customization.md）：

• --add-extension .templ=templ add a new file extension mapping
• --add-query templ struct "(component_declaration ...)" add a structure query
• --language-config <JSON_FILE> use a JSON file for complex configurations

Scan filtering: AST extraction and raw/file_tree.txt generation share the same set of filtering rules:

• --exclude-dirs django_static,.go_root ignore junk directories by directory name or repository-relative path
• --use-gitignore enable <repo_path>/.gitignore rules (enabled by default), ignoring the files and directories declared therein
• --no-gitignore do not apply .gitignore rules; at this time built-in exclusions and --exclude-dirs

---

Output format

After execution completes, the following will be produced in the target repository root directory:

.nexus-map/
├── INDEX.md                    ← AI 冷启动主入口（< 2000 tokens）
├── arch/
│   ├── systems.md              ← 系统边界 + 代码位置
│   ├── dependencies.md         ← Mermaid 依赖图 + 时序图
│   └── test_coverage.md        ← 静态测试面：测试文件、覆盖到的核心模块、证据缺口
├── concepts/
│   ├── concept_model.json      ← Schema V1 机器可读图谱
│   └── domains.md              ← 核心领域概念说明
├── hotspots/
│   └── git_forensics.md        ← Git 热点 + 耦合对分析
└── raw/
    ├── ast_nodes.json          ← Tree-sitter 解析原始数据
    ├── git_stats.json          ← Git 热点与耦合数据
    └── file_tree.txt           ← 过滤后的文件树

All generated Markdown files must have a short header containing at least:generated_by、verified_at、provenance。

concept_model.json The human-readable name fields uniformly use label, do not add title。

If the PROFILE stage discovers language coverage degradation or manual inference,provenance must be explicitly marked.

---

PROBE stage gating

[!IMPORTANT] Before entering each stage, the corresponding reference must be read first, and must not be skipped. Detailed steps for each phase, completion checklists, and handling of edge cases are all defined in the reference.

[Skill 激活时]     → read references/probe-protocol.md  （阶段步骤蓝图，含边界场景与三维度质疑框架）
[EMIT 前]          → read references/output-schema.md    （Schema 校验规范）
[非标准语言时]     → read references/language-customization.md（按需，非门控）

---

Execution Guidelines

Guideline 1: OBJECT rejects formalism

The purpose of OBJECT is to break REASON's survivorship bias. A large amount of engineering facts is hidden behind directory naming and git hotspots, and the first intuition is almost always wrong.

Unqualified challenges (submission prohibited):

Q1: 我对系统结构的把握还不够扎实
Q2: xxx 目录的职责暂时没有直接证据

The problem is not the wording, but that there is no evidence trail and it cannot be verified during the BENCHMARK phase.

Qualified challenge format:

Q1: git_stats 显示 tasks/analysis_tasks.py 变更 21 次（high risk），
    但 HYPOTHESIS 认为编排入口是 evolution/detective_loop.py。
    矛盾：若 detective_loop 是入口，为何 analysis_tasks 热度更高？
    证据线索: git_stats.json hotspots[0].path
    验证计划: view tasks/analysis_tasks.py 的 class 定义 + import 树

---

Guideline 2: implemented nodes must have a real code_path

[!IMPORTANT] Before writing to concept_model.json , you must first distinguish whether the node is implemented、planned or inferred. Only implemented nodes are allowed to write code_path, and its existence must be verified by hand.

# BENCHMARK 阶段验证方式
ls $repo_path/src/nexus/application/weaving/   # 目录存在 → 节点有效
ls $repo_path/src/nexus/application/nonexist/  # [!ERROR] → 修正或删除此节点

For planned or inferred nodes, use:

{
  "implementation_status": "planned",
  "code_path": null,
  "evidence_path": "docs/architecture.md",
  "evidence_gap": "仓库中未发现 src/agents/monarch/，仅在设计文档中出现"
}

Prohibited: passing off barely related files as code_path, stuffing status into the path field (such as code_path: "PLANNED"）。

---

Guideline 3: EMIT atomicity

First write all .nexus-map/.tmp/, and after all succeed, move the whole thing to the formal directory and delete .tmp/. Purpose: a mid-way failure does not leave a half-finished product. On the next execution, if .tmp/ is detected to exist → clean up and regenerate.

Idempotency rules:

Status	Handling method
.nexus-map/ does not exist	Continue directly
.nexus-map/ exists and INDEX.md is valid	Ask the user: "Overwrite? [y/n]"
.nexus-map/ exists but the file is incomplete	"Incomplete analysis detected, will regenerate", continue directly

---

Guideline 4: The role of INDEX.md—cold-start router, not a static dictionary

INDEX.md The reader ofis an AI that has never seen this repository. Two hard constraints:

• < 2000 tokens — if exceeded, rewrite, not truncate
• Conclusions must be specific — when evidence is insufficient, explicitly write evidence gap or unknown, and explain what evidence is missing

After writing, perform a token estimate: number of lines × an average of 30 tokens/line = rough estimate.

Mandatory routing block that INDEX.md must contain (Hard-Trigger Block)—when generating, write this structure at the end of the file:

## [操作指南] 强制执行步骤

> 本节是对所有读取本文件的 AI 发出的硬性操作指令，不是建议。

### 步骤1 — 必须先读完以下所有文件（顺序不限）

读完本文件后，在执行任何任务之前，必须依次 read 以下文件完整内容：

- `.nexus-map/arch/systems.md` — 系统边界与代码位置
- `.nexus-map/arch/dependencies.md` — 系统间依赖关系与 Mermaid 图
- `.nexus-map/arch/test_coverage.md` — 测试面与证据缺口
- `.nexus-map/hotspots/git_forensics.md` — Git 热点与耦合风险
- `.nexus-map/concepts/domains.md` — 核心领域概念

> 这些文件均为高密度摘要，总量通常 < 5000 tokens，是必要的上下文成本。
> 不得以"任务简单"或"只改一个文件"为由跳过。

### 步骤2 — 按任务类型追加操作（步骤1 完成后执行）

- 若任务涉及**接口修改、新增跨模块调用、删除/重命名公共函数**：
  → 必须运行 `query_graph.py --impact <目标文件>` 确认影响半径后再写代码。
- 若任务需要**判断某文件被谁引用**：
  → 运行 `query_graph.py --who-imports <模块名>`。
- 若仓库结构已发生重大变化（新增系统、重构模块边界）：
  → 任务完成后评估是否需要重新运行 nexus-mapper 更新知识库。

---

Guideline 5: Minimal execution surface and sensitive information protection

[!IMPORTANT] By default, only run the scripts bundled with this Skill and the necessary read-only checks. Do not execute the target repository's build scripts, test scripts, or custom commands just because you "want to understand the repository better".

• Allowed by default:extract_ast.py、git_detective.py, directory traversal, text search, read-only file viewing
• Prohibited by default: executing the target repository's npm install、pnpm dev、python main.py、docker compose up , etc., unless the user explicitly requests it
• When encountering .env, key files, or credential configurations: only record their existence and purpose, do not copy out specific values

---

Guideline 6: Degradation and manual inference must be explicitly visible

[!IMPORTANT] If AST coverage is incomplete, or some part comes from manual reading rather than script output, provenance must be explicitly marked in the final file.

• dependencies.md In inferred from file tree/manual inspection
• domains.md、systems.md、INDEX.md If it involves an unsupported language region, it must be stated unsupported language downgrade
• If writing a progress snapshot or Sprint status, you must attach verified_at, to avoid stale information masquerading as current fact

---

Uncertainty Expression Specification

Avoid writing only: to be confirmed · possibly · suspected · perhaps · undetermined · currently unclear · pending · maybe · possibly · TBD

If the evidence is insufficient, write in the following format:

• unknown: 未发现直接证据表明 api/ 是主入口，当前仅能确认 cli.py 被 README 引用
• evidence gap: 仓库没有 git 历史，因此 hotspots 部分跳过

It is allowed to honestly write uncertainty, but you must explain which missing piece of evidence the uncertainty comes from.

---

Script Toolchain

# 设置 SKILL_DIR（根据实际安装路径）
# 场景 A: 作为 .agent/skills 安装
SKILL_DIR=".agent/skills/nexus-mapper"
# 场景 B: 独立 repo（开发/调试时）
SKILL_DIR="/path/to/nexus-mapper"

# PROFILE 阶段 — 基础用法
python $SKILL_DIR/scripts/extract_ast.py <repo_path> [--max-nodes 500] \
  --file-tree-out <repo_path>/.nexus-map/raw/file_tree.txt \
  > <repo_path>/.nexus-map/raw/ast_nodes.json

# 忽略三方静态资源或杂物目录
python $SKILL_DIR/scripts/extract_ast.py <repo_path> [--max-nodes 500] \
  --exclude-dirs django_static,.go_root,third_party/assets \
  --file-tree-out <repo_path>/.nexus-map/raw/file_tree.txt \
  > <repo_path>/.nexus-map/raw/ast_nodes.json

# 若希望忽略内置噪音目录，但不要读取 .gitignore
python $SKILL_DIR/scripts/extract_ast.py <repo_path> [--max-nodes 500] \
  --no-gitignore \
  --file-tree-out <repo_path>/.nexus-map/raw/file_tree.txt \
  > <repo_path>/.nexus-map/raw/ast_nodes.json

# 补充非标准语言支持
python $SKILL_DIR/scripts/extract_ast.py <repo_path> [--max-nodes 500] \
  --add-extension .templ=templ \
  --add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def" \
  > <repo_path>/.nexus-map/raw/ast_nodes.json

# 复杂配置：使用 JSON 配置文件
python $SKILL_DIR/scripts/extract_ast.py <repo_path> [--max-nodes 500] \
  --language-config /custom/path/to/language-config.json \
  > <repo_path>/.nexus-map/raw/ast_nodes.json

Dependency Installation (first use)：

pip install -r $SKILL_DIR/scripts/requirements.txt

---

Persistent Memory Rule (written into the host AGENTS.md)

It is recommended to write the following rules into the repository's AGENTS.md、CLAUDE.md or a similar persistent memory file, so that the knowledge base remains active in long-term conversations:

如果仓库中存在 .nexus-map/INDEX.md，先阅读它，然后在执行任务前读完其路由块中列出的所有文件。

如果 .nexus-map/ 不存在，且当前任务涉及跨模块修改或接口变更，先向用户提议运行 nexus-mapper；若用户需立即开始，至少先运行 query_graph.py --summary 建立结构感知。

当任务改变了项目的结构认知（系统边界、入口、依赖关系），在交付前评估是否需要更新 .nexus-map。

---

On-demand Query Tools (PROBE assistance)

scripts/query_graph.py reads raw/ast_nodes.json, with zero additional dependencies (pure Python standard library).

python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --file <path>         # 文件骨架
python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --who-imports <mod>   # 反向依赖
python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --impact <path>       # 影响半径
python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --impact <path> --git-stats <git_stats.json>
python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --hub-analysis        # 核心节点
python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --summary             # 目录聚合

Phase	Recommended Query	Purpose
REASON	--hub-analysis	Validate core system hypotheses with data, not by guessing from directory names
OBJECT	--impact --git-stats	Validate boundary assumptions and view real upstream and downstream dependencies
EMIT	--summary, --file	Generate data support for systems.md / dependencies.md

The core value of each query mode:--hub-analysis is used in the REASON phase to validate architectural hypotheses;--impact --git-stats is used in the OBJECT phase to quantify boundary risks;--summary and --file are used in the EMIT phase to generate precise data support.