@haaaiawd/anws 2.3.0 → 2.4.0

package/templates_en/.agents/skills/nexus-mapper/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: nexus-mapper
+description: "Generate a persistent .nexus-map/ knowledge base that lets any AI session instantly understand a codebase's architecture, systems, dependencies, and change hotspots. Use when starting work on an unfamiliar repository, onboarding with AI-assisted context, preparing for a major refactoring initiative, or enabling reliable cold-start AI sessions across a team. Produces INDEX.md, systems.md, concept_model.json, git_forensics.md and more. Requires shell execution and Python 3.10+. For ad-hoc file queries or instant impact analysis during active development, use nexus-query instead."
+---
+
+# nexus-mapper — AI Project Exploration Protocol
+
+This Skill guides AI Agents to use the **PROBE Five-Phase Protocol** to systematically explore any local Git repository and produce a `.nexus-map/` layered knowledge base.
+
+---
+
+## When to Call / When Not to Call
+
+| Scenario                                                                | Call  |
+| ----------------------------------------------------------------------- | :---: |
+| User provides local repo path, wants AI to understand its architecture  |  Yes  |
+| Need to generate `.nexus-map/INDEX.md` for subsequent AI session cold start |  Yes  |
+| User says "help me analyze project", "build project knowledge base", "let AI understand this repo" |  Yes  |
+| Runtime environment has no shell execution capability (pure API mode, no `run_command` tool) |  No   |
+| Host machine has no local Python 3.10+                                  |  No   |
+| Target repo has no known language source files (no `.py/.ts/.java/.go/.rs/.cpp` etc.) |  No   |
+| User only wants to query specific file/function → use `view_file` / `grep_search` directly |  No   |
+
+---
+
+## Prerequisite Check
+
+Explicitly inform users of missing items; remind users when downgrade is needed, continue only after consent.
+
+| Prerequisite         | Check Method                                |
+| ------------------- | ------------------------------------------- |
+| Target path exists  | `$repo_path` accessible                    |
+| Python 3.10+        | `python --version` >= 3.10                  |
+| Script deps installed | `python -c "import tree_sitter"` no error  |
+| Has shell execution | Agent environment supports `run_command` tool call |
+
+`git` history is a bonus, not a hard blocker. When no `.git` or insufficient history, skip hotspot analysis and explicitly record in output that this is a degraded exploration.
+
+---
+
+## Input Contract
+
+```
+repo_path: Local absolute path to target repository (required)
+```
+
+**Language support**: Automatically dispatch by file extension, language configuration (extension mapping + Tree-sitter queries) stored in `scripts/languages.json`. Currently supports 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 and 30+ languages.
+
+**Non-standard languages**: If repo contains unsupported languages, dynamically supplement via command line args (see `references/language-customization.md`):
+- `--add-extension .templ=templ` add new file extension mapping
+- `--add-query templ struct "(component_declaration ...)"` add structure query
+- `--language-config <JSON_FILE>` use JSON file for complex configuration
+
+---
+
+## Output Format
+
+After execution, target repository root will produce:
+
+```text
+.nexus-map/
+├── INDEX.md                    ← AI cold start main entry (< 2000 tokens)
+├── arch/
+│   ├── systems.md              ← System boundaries + code locations
+│   ├── dependencies.md         ← Mermaid dependency graph + sequence diagram
+│   └── test_coverage.md        ← Static test surface: test files, covered core modules, evidence gaps
+├── concepts/
+│   ├── concept_model.json      ← Schema V1 machine-readable graph
+│   └── domains.md              ← Core domain concept explanations
+├── hotspots/
+│   └── git_forensics.md        ← Git hotspots + coupling pair analysis
+└── raw/
+    ├── ast_nodes.json          ← Tree-sitter parsed raw data
+    ├── git_stats.json          ← Git hotspots and coupling data
+    └── file_tree.txt           ← Filtered file tree
+```
+
+All generated Markdown files must include a brief header, at minimum containing: `generated_by`, `verified_at`, `provenance`.
+
+Human-readable name fields in `concept_model.json` uniformly use `label`, do not add `title`.
+
+If PROFILE phase detects language coverage downgrade or manual inference, `provenance` must be explicitly marked.
+
+---
+
+## PROBE Phase Gate
+
+> [!IMPORTANT]
+> **Must read corresponding reference before entering each phase, do not skip.**
+> Detailed steps, completion checklists, and boundary scenario handling for each phase are defined in references.
+
+```
+[Skill activation]     → read references/probe-protocol.md  (phase step blueprint, includes boundary scenarios and three-dimensional questioning framework)
+[Before EMIT]          → read references/output-schema.md    (Schema validation spec)
+[Non-standard language] → read references/language-customization.md (as needed, not gated)
+```
+
+---
+
+## Execution Rules
+
+### Rule 1: OBJECT Rejects Formalism
+
+The purpose of OBJECT is to break REASON's survivor bias. Massive engineering facts hide behind directory naming and git hotspots, first intuition is almost always wrong.
+
+Unqualified challenges (prohibited to submit):
+```
+Q1: My grasp of system structure is not solid enough
+Q2: xxx directory responsibilities have no direct evidence yet
+```
+Problem is not wording, but lack of evidence clues, nor can it be verified in BENCHMARK phase.
+
+Qualified challenge format:
+```
+Q1: git_stats shows tasks/analysis_tasks.py changed 21 times (high risk),
+    but HYPOTHESIS thinks orchestration entry is evolution/detective_loop.py.
+    Contradiction: If detective_loop is entry, why is analysis_tasks hotter?
+    Evidence clue: git_stats.json hotspots[0].path
+    Verification plan: view tasks/analysis_tasks.py class definition + import tree
+```
+
+---
+
+### Rule 2: implemented Nodes Must Have Real code_path
+
+> [!IMPORTANT]
+> Before writing to `concept_model.json`, must first distinguish if node is `implemented`, `planned`, or `inferred`.
+> Only `implemented` nodes allowed to write `code_path`, and must personally verify existence.
+
+```bash
+# BENCHMARK phase verification method
+ls $repo_path/src/nexus/application/weaving/   # directory exists → node valid
+ls $repo_path/src/nexus/application/nonexist/  # [!ERROR] → fix or delete this node
+```
+
+For `planned` or `inferred` nodes, use:
+
+```json
+{
+  "implementation_status": "planned",
+  "code_path": null,
+  "evidence_path": "docs/architecture.md",
+  "evidence_gap": "src/agents/monarch/ not found in repo, only appears in design docs"
+}
+```
+
+Prohibited: using barely related files to fake `code_path`, stuffing status into path field (like `code_path: "PLANNED"`).
+
+---
+
+### Rule 3: EMIT Atomicity
+
+First write everything to `.nexus-map/.tmp/`, after all successful move all to formal directory, delete `.tmp/`.
+Purpose: no half-finished products on mid-failure. Next execution detects `.tmp/` exists → clean up and regenerate.
+
+Idempotency rules:
+
+| State                                   | Handling                                    |
+| --------------------------------------- | ------------------------------------------- |
+| `.nexus-map/` does not exist            | Continue directly                           |
+| `.nexus-map/` exists and `INDEX.md` valid | Ask user: "Overwrite? [y/n]"               |
+| `.nexus-map/` exists but files incomplete | "Detected incomplete analysis, will regenerate", continue directly |
+
+---
+
+### Rule 4: INDEX.md Role — Cold Start Router, Not Static Dictionary
+
+Readers of `INDEX.md` are **AI that have never seen this repo before**. Two hard constraints:
+- **< 2000 tokens** — rewrite if exceeded, not truncate
+- **Conclusions must be specific** — when evidence insufficient, explicitly write `evidence gap` or `unknown`, and explain what evidence is missing
+
+After writing, execute token estimation: line count × average 30 tokens/line = rough value.
+
+**INDEX.md must include mandatory routing block (Hard-Trigger Block)** — write this structure at end of file when generating:
+
+```markdown
+## [Operation Guide] Mandatory Execution Steps
+
+> This section issues hard operation instructions to all AI reading this file, not suggestions.
+
+### Step 1 — Must First Read All Following Files (order unrestricted)
+
+After reading this file, before executing any task, must sequentially read full content of following files:
+
+- `.nexus-map/arch/systems.md` — System boundaries and code locations
+- `.nexus-map/arch/dependencies.md` — Inter-system dependencies and Mermaid graphs
+- `.nexus-map/arch/test_coverage.md` — Test surface and evidence gaps
+- `.nexus-map/hotspots/git_forensics.md` — Git hotspots and coupling risks
+- `.nexus-map/concepts/domains.md` — Core domain concepts
+
+> These files are all high-density summaries, total usually < 5000 tokens, necessary context cost.
+> Do not skip with excuse "task simple" or "only changing one file".
+
+### Step 2 — Add Operations by Task Type (execute after Step 1 complete)
+
+- If task involves **interface modification, new cross-module calls, delete/rename public functions**:
+  → Must run `query_graph.py --impact <target file>` to confirm impact radius before writing code.
+- If task needs to **determine who references certain file**:
+  → Run `query_graph.py --who-imports <module name>`.
+- If repo structure has major changes (new system, refactored module boundaries):
+  → After task completion, evaluate whether need to re-run nexus-mapper to update knowledge base.
+```
+
+---
+
+### Rule 5: Minimal Execution Surface and Sensitive Information Protection
+
+> [!IMPORTANT]
+> By default only run this Skill's own scripts and necessary read-only checks. Do not execute target repo's build scripts, test scripts, or custom commands just because "want to understand repo better".
+
+- By default allowed: `extract_ast.py`, `git_detective.py`, directory traversal, text search, read-only file viewing
+- By default prohibited: execute target repo's `npm install`, `pnpm dev`, `python main.py`, `docker compose up`, etc., unless user explicitly requests
+- When encountering `.env`, key files, credential configs: only record their existence and purpose, do not copy out specific values
+
+---
+
+### Rule 6: Downgrade and Manual Inference Must Be Explicitly Visible
+
+> [!IMPORTANT]
+> If AST coverage is incomplete, or certain parts come from manual reading rather than script output, must explicitly mark provenance in final files.
+
+- In `dependencies.md`, any dependency relationship not directly supported by AST must mark `inferred from file tree/manual inspection`
+- `domains.md`, `systems.md`, `INDEX.md` if involving unsupported language areas, must explain `unsupported language downgrade`
+- If writing progress snapshots, Sprint status, must attach `verified_at`, avoid expired info masquerading as current fact
+
+---
+
+## Uncertainty Expression Specification
+
+Avoid only writing: pending · maybe · possibly · TBD
+
+If evidence insufficient, write in following format:
+- `unknown: No direct evidence found indicating api/ is main entry, currently only can confirm cli.py is referenced by README`
+- `evidence gap: Repo has no git history, therefore hotspots section skipped`
+
+Allowed to honestly write uncertainty, but must explain which missing evidence causes uncertainty.
+
+---
+
+## Script Toolchain
+
+```bash
+# Set SKILL_DIR (adjust based on actual installation path)
+# Scenario A: Installed as .agent/skills
+SKILL_DIR=".agent/skills/nexus-mapper"
+# Scenario B: Independent repo (during development/debugging)
+SKILL_DIR="/path/to/nexus-mapper"
+
+# PROFILE phase — basic usage
+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
+
+# Add non-standard language support
+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
+
+# Complex configuration: use JSON config file
+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)**:
+```bash
+pip install -r $SKILL_DIR/scripts/requirements.txt
+```
+
+---
+
+## Persistent Memory Rules (write to host AGENTS.md)
+
+Suggest writing following rules to repo's `AGENTS.md`, `CLAUDE.md` or similar persistent memory files, keeping knowledge base active in long-term conversations:
+
+```md
+If .nexus-map/INDEX.md exists in repo, read it first, then read all files listed in its routing block before executing tasks.
+
+If .nexus-map/ does not exist, and current task involves cross-module modification or interface changes, first propose running nexus-mapper to user; if user needs to start immediately, at least run query_graph.py --summary first to establish structure awareness.
+
+When task changes project structure cognition (system boundaries, entry points, dependencies), evaluate before delivery whether need to update .nexus-map.
+```
+
+---
+
+## On-Demand Query Tools (PROBE auxiliary)
+
+`scripts/query_graph.py` reads `raw/ast_nodes.json`, zero extra dependencies (pure Python standard library).
+
+```bash
+python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --file <path>         # file skeleton
+python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --who-imports <mod>   # reverse dependency
+python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --impact <path>       # impact radius
+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        # core nodes
+python $SKILL_DIR/scripts/query_graph.py <ast_nodes.json> --summary             # directory aggregation
+```
+
+| Phase   | Recommended Query       | Purpose                                          |
+| -------- | ---------------------- | ------------------------------------------------ |
+| REASON   | `--hub-analysis`       | Data validate core system hypothesis, not guess by directory name |
+| OBJECT   | `--impact --git-stats` | Validate boundary hypothesis, view real upstream/downstream dependencies |
+| EMIT     | `--summary`, `--file`  | Generate data support for systems.md / dependencies.md |
+
+Core value of each query mode: `--hub-analysis` for validating architecture hypothesis in REASON phase; `--impact --git-stats` for quantifying boundary risk in OBJECT phase; `--summary` and `--file` for generating precise data support in EMIT phase.

package/templates_en/.agents/skills/nexus-mapper/references/language-customization.md

@@ -0,0 +1,167 @@
+# Adding Language Support for nexus-mapper
+
+> This file is not a phase gate file. When built-in language coverage is insufficient, subsequent agents should prioritize referencing this file to supplement support via command line arguments; only use explicit JSON config file when configuration is complex.
+
+---
+
+## Goal
+
+The default model of current scripts is:
+
+1. First use built-in extension mapping and built-in Tree-sitter query
+2. If built-in coverage insufficient, then agent supplements language support via command line
+3. If command line args too many or query too long, then fall back to `--language-config <JSON_FILE>`
+
+This means:
+
+- Does not require repo to have fixed path language config file
+- Not recommended to modify core scripts for single repo single analysis
+- New agent can directly plug additional languages into analysis flow in one command
+
+---
+
+## Preferred Approach: Command Line Supplement
+
+### Applicable Scenarios
+
+Prioritize command line when following conditions met:
+
+- Repo contains extensions not covered by built-in
+- Only need to supplement 1-3 language mappings
+- Query is short, suitable for inline in command line
+
+### Step 1: Confirm Language Name
+
+First confirm language name recognizable by `tree-sitter-language-pack` or current environment. For example:
+
+- `.templ` -> `templ`
+- `.hbs` -> `handlebars`
+- `.rego` -> `rego`
+
+If language name uncertain, first check official grammar name; do not guess a language name and directly write into final conclusion.
+
+### Step 2: Supplement Extension Mapping
+
+```bash
+python extract_ast.py <repo_path> \
+  --add-extension .templ=templ \
+  --add-extension .hbs=handlebars
+```
+
+This brings originally unrecognized extensions into language dispatch flow.
+
+### Step 3: Supplement Query as Needed
+
+If only Module-level coverage needed, can stop here.
+
+If need class/function-level structure, continue appending `--add-query`:
+
+```bash
+python extract_ast.py <repo_path> \
+  --add-extension .templ=templ \
+  --add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def"
+```
+
+Parameter format:
+
+```text
+--add-query <LANG> <TYPE> <QUERY_STRING>
+```
+
+Where:
+
+- `<LANG>`: language name, e.g., `templ`
+- `<TYPE>`: `struct` or `imports`
+- `<QUERY_STRING>`: Tree-sitter query string
+
+Capture naming must continue to follow existing convention:
+
+- Class: `@class.def` / `@class.name`
+- Function: `@func.def` / `@func.name`
+- Import: `@mod`
+
+---
+
+## Alternative Approach: Explicit JSON Config File
+
+When any of following holds, can use `--language-config`:
+
+- Need to supplement multiple languages, command line already too long
+- Query is complex, not suitable for inline in shell command
+- Want to centrally save extension mapping and query needed for one analysis
+
+Example:
+
+```json
+{
+  "extensions": {
+    ".templ": "templ",
+    ".hbs": "handlebars"
+  },
+  "queries": {
+    "templ": {
+      "struct": "(component_declaration name: (identifier) @class.name) @class.def",
+      "imports": ""
+    }
+  },
+  "unsupported_extensions": {
+    ".legacydsl": "legacydsl"
+  }
+}
+```
+
+Execution method:
+
+```bash
+python extract_ast.py <repo_path> --language-config /custom/path/to/language-config.json
+```
+
+Explanation:
+
+- `extensions`: extension to language name mapping
+- `queries`: custom `struct` / `imports` query
+- `unsupported_extensions`: explicitly declare extensions still not currently supported, avoid silent skip
+
+This JSON file is explicit input for one analysis, does not require fixed placement in repo default location.
+
+---
+
+## Coverage Honesty Rules
+
+Whether command line or explicit JSON, new languages must follow same layered standard:
+
+1. `structural coverage`
+  Condition: parser loadable, and `struct` query exists
+2. `module-only coverage`
+  Condition: parser loadable, but no `struct` query
+3. `configured-but-unavailable`
+  Condition: agent explicitly requested support for this language, but current environment cannot load parser
+4. `unsupported`
+  Condition: language still not included in this AST flow, or explicitly marked as unsupported
+
+Prohibited:
+
+- Write `configured-but-unavailable` as `module-only`
+- Disguise `unsupported` as "not present in repo"
+
+---
+
+## Recommended Decision Order
+
+When subsequent agent encounters an uncovered language, handle in following order:
+
+1. First confirm whether that extension file actually exists in current repo
+2. Then confirm whether current environment can load corresponding parser
+3. If loadable: prioritize `--add-extension`; supplement `--add-query` when need structure nodes
+4. If command too long: switch to `--language-config`
+5. If parser cannot load: keep `configured-but-unavailable`, do not fake results
+
+---
+
+## Design Principles
+
+- Built-in languages first, command line supplement second, explicit JSON last
+- For single analysis, prioritize minimum extra input, do not modify core scripts first
+- Custom query is formal input, not bypass hack
+- All new languages must follow same metadata and provenance rules
+