AGENT SKILL

atlas-traverse

Phase T (Traverse) — deterministic structural mapping of a codebase. Zero LLM calls during retrieval; only symbol index, AST, ripgrep, and git log. Emits map.md with entrypoints, modules, call graph, and heatmap. Use after mission.md is valid and before any meaning-based search. Trigger phrases — "map the repo", "what are the entrypoints", "build the call graph", "list all routes/workers/CLIs".

License 许可
Apache-2.0
所属仓库
Rynaro/magicite
最近更新
2026-10-14
Stars
★ 2
Forks
0

01 前言 Front Matter

name
atlas-traverse
metadata
{ "phase": "T", "methodology": "ATLAS" }
description
Phase T (Traverse) — deterministic structural mapping of a codebase. Zero LLM calls during retrieval; only symbol index, AST, ripgrep, and git log. Emits map.md with entrypoints, modules, call graph, and heatmap. Use after mission.md is valid and before any meaning-based search. Trigger phrases — "map the repo", "what are the entrypoints", "build the call graph", "list all routes/workers/CLIs".
allowed-tools
view_file list_dir search_text search_symbol graph_query

03 SKILL.md 正文

SKILL: Traverse — structural mapping (Phase T)

When to use

Load when: Phase A (Assess) has produced a valid mission.md and you are about to emit map.md.

Unload when: map.md passes exit criteria and you enter Phase L (Locate).

Memory pre-flight: recall MUST have fired in Phase A (see PERSONA.md §"Memory pre-flight") before Phase T begins. If it hasn't — e.g. this skill was loaded directly — call it now with the mission objective and target paths before any structural mapping. Fold relevant prior maps and known traps into your mission context. If mcp__crystalium__* tools are unavailable, proceed without memory — never hard-fail.


Contract

Field Value
LLM calls permitted Zero during retrieval. LLM used only to author the final map.md summary.
Tool budget ≤ 20% of mission max_tool_calls
Output map.md conforming to templates/traversal-map.md

If you find yourself reasoning about meaning, stop — that's Phase L. Traverse is about structure.


Deterministic retrieval ladder

Try in order. Stop at the first that works for the mission scope.

1. Code-graph MCP server (preferred)

If the host provides a code-graph server (e.g. Sourcegraph, a Tree-sitter index over MCP, a Prism-based graph for Ruby):

graph.roots(scope=<globs>)                 # entrypoints
graph.modules(scope=<globs>, top_n=20)     # centrality-ranked
graph.edges(scope=<globs>, kind=call|import|inherit)

These are O(1) lookups into an indexed structure. No file reads.

2. Language-native AST

For single-language repos without a graph server:

  • Ruby → prism (Prism.parse_file, walk CallNode / DefNode)
  • Python → stdlib ast
  • TypeScript/JavaScript → @typescript-eslint/parser or tree-sitter-typescript
  • Go → go/ast + go/types
  • Anything else → Tree-sitter with the appropriate grammar

Emit a small script via execute_read_only_script (if the harness allows it) or delegate to a deterministic MCP tool. Never paste file contents into the LLM to "parse" them. That's the Inference Trap.

3. rg (ripgrep) for coarse structural signals

When AST is unavailable or the scope crosses languages:

rg --files <scope>                 # file enumeration
rg -l '^class |^module ' <scope>   # class/module surface
rg -l 'Rails.application.routes'   # routing entrypoints

Always use --files or -l (filenames only) at this stage. You are not reading content yet.

4. git log for heatmap

git log --since='90 days' --name-only --pretty=format: <scope> | sort | uniq -c | sort -rn | head -30
git log --follow --format='%an' <file> | sort | uniq -c | sort -rn

Produces MAP-HEATMAP entries: churn + primary contributors. Optional but high-signal for risk assessment.


Entrypoint taxonomy (MAP-ROOTS)

The mission DECISION_TARGET almost always traces back to one of:

  • HTTP routes (Rails routes, Express/Koa handlers, FastAPI, gRPC services)
  • Background workers (Sidekiq, Celery, RQ, Temporal workflows)
  • CLI entrypoints (bin/, rake tasks, click/cobra commands)
  • Public library API (gem top-level, __init__.py re-exports, package main)
  • Event handlers (webhooks, message consumers, scheduled jobs)
  • Test surfaces (integration tests as executable specs of behavior)

Identify the root category relevant to the mission and enumerate exhaustively within scope. Ignore others.


What to skip by default

Hardcoded skip list (override only when mission explicitly requires):

node_modules/   vendor/bundle/    vendor/cache/
tmp/            log/              .git/
dist/           build/            public/assets/
coverage/       .bundle/          __pycache__/
*.min.js        *.map             *.lock

Generated code and vendored dependencies are noise at this phase.


Ambiguity handling

  • Monorepo? Ask which package(s) the mission applies to. Don't guess.
  • Multi-language? Build MAP-MODULES per language; edges only within language.
  • Un-parseable file? Record in MAP-GAPS, don't retry with different parsers.

Exit gate

Before emitting map.md, check:

  • [ ] MAP-ROOTS is non-empty and every entry is a real file.
  • [ ] MAP-MODULES top-N is ranked by a deterministic metric, not by LLM guess.
  • [ ] MAP-GRAPH edges are all AST-derived or graph-server-derived, never LLM-inferred.
  • [ ] MAP-GAPS lists every region the index couldn't parse.
  • [ ] Total token cost for Phase T ≤ 20% of mission budget.

If any fails, the mission is likely out of scope or the toolchain is insufficient — halt and report.


Common anti-patterns

Anti-pattern Why it's wrong Fix
"Let me read app/controllers/*.rb to understand routing" Wastes thousands of tokens on content the router already knows Query Rails.application.routes.routes or parse config/routes.rb with Prism
"I'll grep for class.*Service" Captures junk, misses the real hierarchy Use AST to get every class declaration with its superclass
"Give me a summary of this module" That's interpretation, i.e. Phase L Traverse answers what exists, not what it means
Loading AST of every file "just in case" Blows the budget before Locate starts Build the map from structural signals; let Locate zoom in

04 同仓库更多 Skills

Rynaro
Rynaro/magicite

wine-dxvk-cache-clear

Clear a stale DXVK shader cache that is causing graphical corruption in a Wine or Proton game. Use when: a game shows corrupted textures or shader flicker that started after a driver or DXVK version change.

★ 2
Rynaro
Rynaro/magicite

steam-download-region-fix

Fix a Steam client stuck at very low download speed by changing its download region. Use when: Steam downloads are far below the local internet speed for every game, not just one.

★ 2
Rynaro
Rynaro/magicite

proton-battleye-eac-toggle

Toggle BattlEye or Easy Anti-Cheat runtime support for a Steam Proton game. Use when: a multiplayer game refuses to launch with an anti-cheat error under Proton.

★ 2
Rynaro
Rynaro/magicite

vivi-verify-incoming

Load when reading any upstream artefact handed off to Vivi that carries a sibling .envelope.json. BLOCKING per ECL §6.2.2: the orchestrator MUST have verified the envelope's SHA-256 (eidolons verify-envelope --block / eidolons run --verify) and recorded a verify_pass before dispatch. If no verify_pass exists for the message_id, or a verify_fail is present, REFUSE to process the payload and hand back to the orchestrator. Symmetric receiver gate — every Eidolon enforces it identically.

★ 2
Rynaro
Rynaro/magicite

vivi-parallel-tracks

Load ONLY under TRANCE authorization when the Plan phase yields N independent, non-overlapping implementation tracks (disjoint file sets). Operationalizes the TRANCE G4 form — parallel multi-track implementation in mandatory git-worktree isolation, max 5 clean-context tracks, a per-track verifier cascade, a non-fungible per-track ≤3 reflection budget, explicit stop conditions, and a single-threaded merge/aggregation step. Absent TRANCE gating, Vivi runs exactly as today: single-track A→P→I→V→Δ/R.

★ 2
Rynaro
Rynaro/magicite

vivi-methodology

Full Vivi cycle reference — A(nalyze) → P(lan) → I(mplement) → V(erify) → Δ(Delta)/R(eflect). Use when the task is a non-trivial feature implementation in a brownfield codebase and you need the complete methodology reference: complexity routing, evidence-grounded planning rules, test-anchoring requirements, and failure-escalation thresholds.

★ 2