# Code Context Map > |- - **Type:** Skill - **Install:** `agentstack add skill-mozurok-fhorja-dev-code-context-map` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Mozurok](https://agentstack.voostack.com/s/mozurok) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Mozurok](https://github.com/Mozurok) - **Source:** https://github.com/Mozurok/fhorja.dev/tree/main/.claude/skills/code-context-map - **Website:** https://fhorja.dev ## Install ```sh agentstack add skill-mozurok-fhorja-dev-code-context-map ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Act as a senior/staff engineer producing a durable, AI-readable structural map of a codebase. Goal: Generate a ranked, token-budgeted, layered Markdown "code context map" of a target project (files, imports, signatures, invoke edges, and typed external boundary calls), write it to a gitignored folder inside that project, and regenerate it on invoke so an AI assistant reads the map first and knows precisely what to read, index, and test before changing code. A `chain:` scope additionally walks one file's import chain by direction with a hop cap, extracting with ripgrep by default and with a parser when one is already present (ADR-0057 D-2, D-5). The map ORIENTS; it is a seed for `grep`, not a replacement for reading the code. Follows `templates/CODE_CONTEXT_MAP.template.md`. This command is opt-in, not part of default task init (use it for structural orientation, onboarding, or a stale map). The governing decision is `docs/adr/0027-code-context-map-and-product-repo-artifacts.md`. Mandatory context bootstrap (before any output): - Read these sections in `WORKFLOW_OPERATING_SYSTEM.md` first: - `## LLM execution contract` - `## Editor mode policy` (mode definitions only; the tool mapping table is lazy-loaded in `wos/editor-mode-mappings.md` and needed only for non-Claude-Code tools) - `## Global output contract` (including **Adaptive handoff** and **Mode selection rule**) - `## Cross-cutting workflow guardrails` - **Bootstrap tiers (ADR-0025):** the light-weight commands (`branch-commit`, `what-next`, `where-we-at`, `slice-closure`, `compact-task-memory`) may skip `## Editor mode policy` good-fits lists and `## Cross-cutting workflow guardrails` sequencing heuristics, reading only the mode definitions and the core guardrail rules (routing memory, command-less input triage, official command names, material change, no-op). This reduces bootstrap from ~6,750 to ~3,500 tokens for these commands. - Read additional sections only when relevant to this command's role. - Read the `commands/` directory command inventory to ensure command names and availability are current. - Align all routing recommendations and next-command suggestions with the current command set. - **Official next-command names only:** every recommended next command (including the handoff `Run now` line) MUST be the basename of an existing `commands/.md` file in this workflow repository. Never invent names. Required inputs: - target codebase path (the project to map; the map is written inside this path). When a task is active and `SOURCE_OF_TRUTH.md` names the workspace, default to that. - scope, one of: - `digest` (default): Layer 1 only (repo digest + module-to-file import adjacency + boundary summary). Cheapest; always safe for a whole repo. - `module:`: Layer 1 plus Layer 2 detail (ranked signatures, invoke edges, typed boundary edges) for the named module(s). Use for the area the current task touches. - `chain:`: Layer 1 plus a seed-anchored import-chain walk from `` (ADR-0057 D-5). Answers "what does this file pull in, and in what order does the wiring run". Walks by direction with a hop cap and a cycle guard. - optional (chain scope only): `direction` one of `imports` (default), `dependents`, or `both`; `max-hops` (default 4, or `all` for an unbounded walk until no new files are reached) caps the radius; cycle edges are recorded once and not re-walked. For a whole-repo view prefer the `digest` or `module:` scopes; a `chain:` with `max-hops:all` on a large repo trips the consent-gated fleet (D-4) by design. - optional: token budget for Layer 2 (default 1200 tokens per module; raise only when justified). Layer 1 is always generated regardless of budget. - optional: `keywords:` (task-scoped) to rerank Layer 2 symbols toward the current task. WHEN set, Layer 2 symbols are reranked by ripgrep term-frequency of these terms blended with the existing import fan-in via reciprocal rank fusion (RRF), and that Layer 2's ranking source is labeled `structural + keyword`. WHEN unset, ranking is import fan-in only, the source is labeled `structural`, and the output is byte-identical to prior behavior. Ripgrep-only: no embeddings and no vector index (ADR-0072, activating the optional rerank ADR-0027 D-8 deferred). - optional: `--explain-ranking` flag to show, per Layer 2 symbol, its fan-in rank, its keyword-frequency rank, and the fused RRF score, so a reranked order is auditable. Off by default; WHEN off, the symbol-line format is unchanged, and WHEN `keywords:` is absent the flag adds nothing beyond the fan-in rank. - optional: language hint (defaults to auto-detect by file extension; v1 ships pattern sets for TS/JS first and degrades gracefully elsewhere). - optional: refresh flag (`refresh` to regenerate an existing map; default behavior is regenerate-on-invoke, so a non-stale identical map yields `NO_OP` rather than a rewrite). - optional: `--skip-secret-scan` to bypass the pre-emit secret gate (ADR-0060); the command never auto-skips, so this is the explicit human override after a confirmed false positive. - optional flags, host-rendered with no new dependency (full behavior in Operating rules below): `diagram` (append a Mermaid import-adjacency and invoke flowchart, node-capped, ADR-0047); `sequence:` (append a Mermaid sequenceDiagram for one named runtime flow); `exemplars` (1 to 3 blessed in-repo reference snippets a greenfield slice should mirror, ranked by fan-in); `html` (also emit a self-contained interactive `MAP.html` in the same gitignored folder, ADR-0057 D-3). Files to read (in the target codebase, read-only): - source files in scope, via `rg` queries for imports, definitions/signatures, invoke sites, and boundary call-sites (db/http/queue). Never modify source, because this command produces a read-only orientation aid; writing to the target would turn a navigation map into an unreviewed code change. Files to create or update: - `/.code-context-map/MAP.md` (the artifact; create or fully regenerate, never partial-merge). - `/.code-context-map/MAP.html` (only when the `html` flag is set: the self-contained human projection; create or fully regenerate, never partial-merge). - `/.gitignore` (append-only: ensure `.code-context-map/` is ignored if not already; the only product-repo file outside `.code-context-map/` that this command may touch). - active task `SOURCE_OF_TRUTH.md`, when a task is active (append-only: add a single `## Code context map` section pointing to the artifact path, if not already present). Operating rules: - Do not implement or modify production code. This command reads code and writes only the gitignored map artifacts (MAP.md, and MAP.html when `html` is set) plus a `.gitignore` entry. - **Gitignored artifact (D-1, ADR-0027):** the map lives in `/.code-context-map/` and MUST be gitignored. Before writing, ensure `.code-context-map/` is present in the target repo's `.gitignore`; if not, append it. Never commit the map; never write it outside the gitignored folder. - **Pre-emit secret gate (ADR-0060):** before writing MAP.md (and MAP.html), run `scripts/secret-scan-gate.sh ` over the in-scope path, because the map summarizes a repo that may hold credentials and the gate is a hard stop, not advisory text. It is presence-gated (ADR-0027): gitleaks if present (a finding BLOCKS the write, exit 1), else trufflehog `--no-verification` (offline; a finding BLOCKS), else a built-in rg pattern scan that WARNS only (coarse regex is too false-positive-prone to gate on). On a BLOCK, do NOT write the map: surface the findings, tell the user to revoke or whitelist (`gitleaks:allow`), and require the explicit `--skip-secret-scan` input to proceed. The command never auto-skips. - **Regenerate-on-invoke (D-6):** always regenerate from the live working tree. Record `Last generated: YYYY-MM-DD on @` in the artifact. If the freshly generated map is byte-identical to the existing one, report `NO_OP` and do not rewrite. - **Layering (D-7, D-11):** always generate Layer 1 (repo digest + module import adjacency + boundary summary). Generate Layer 2 detail only for in-scope module(s) and only within the token budget. Never emit a flat signature-level dump of an entire large repo (it blows the budget and causes context rot). - **Extraction (D-10, amended by ADR-0057 D-2):** use ripgrep-based extraction (imports, definitions/signatures, invoke sites, boundary call-sites) assembled by reasoning. Do NOT require or install an AST parser, vector DB, or embedding model. Optional, only-if-already-present augmentation: `npx madge` / `dependency-cruiser`, or a tree-sitter already present, for a precise JS/TS file-import graph. For the `chain:` scope, WHERE such a parser is already present use it to resolve barrels, default and dynamic imports, and aliases in the chain; WHILE only ripgrep is available, label the chain `grep-seed (non-authoritative)` and do not present it as a faithful import chain. Never install a parser; the ripgrep walk is always the working default. - **Layer 2 compression (presence-gated, ADR-0027 no-install + ADR-0057 D-2):** WHERE `repomix` is already present in the target repo, run `npx repomix --compress` to source Layer 2 from its tree-sitter signatures-only extraction (function and method signatures, interface and type definitions, class shapes; implementations, loop and conditional bodies, and internal variables stripped; roughly 70% fewer tokens than full files) and label that Layer 2 `source: repomix --compress`. WHILE `repomix` is absent, fall back to the ripgrep signature heuristics labeled `source: ripgrep (heuristic)`. Never install repomix; this is opt-in augmentation and the labeled fallback keeps the default path unchanged. - **Chain walk (ADR-0057 D-5):** for `chain:`, start at the seed and follow imports breadth-first by `direction` up to `max-hops` (or until no new files are reached when `max-hops:all`); record each file once (cycle guard), rank modules within a hop by import fan-in, and stop at the cap. The import chain is additive to Layer 1; never emit a flat whole-repo signature dump for a chain scope. - **Generation path (ADR-0057 D-4; Workflow tool, ADR-0038):** generate the map in a single pass by default. WHERE the traversal needed to satisfy the scope is estimated to exceed a single context window (starting heuristic, adjustable: more than ~150 in-scope files to read, or a `chain:` walk that would pull more than ~80 files or ~25k tokens of source in one pass), STOP before generating and present a consent prompt naming the scope, the estimated worker count, what each worker will read, and that partials are merged by one writer. Only on explicit user consent dispatch a Workflow fleet (ADR-0038): one worker per disjoint sub-tree or module-group, each writing a partial, merged into the single MAP.md (and MAP.html when `html` is set) by this command as the sole writer. IF the user declines THEN produce a single-pass bounded map: cap the traversal at the budget and label it `bounded (partial)` in the artifact. Never fan out without explicit consent. - **Ranking (D-12, extended by ADR-0072):** rank symbols and modules by internal import fan-in, most-relevant-first. WHEN no `keywords:` are provided, this fan-in-only order is the default, that Layer 2 is labeled ranking source `structural`, and the output is byte-identical to prior behavior (no keyword rerank runs). WHEN `keywords:` are provided, rerank Layer 2 symbols by blending fan-in with ripgrep keyword term-frequency via reciprocal rank fusion (see the keyword rerank rule below) and label that Layer 2 ranking source `structural + keyword`. Import fan-in stays the primary structural signal; the keyword signal only reorders within the same candidate set, it never adds or removes symbols. No embeddings and no vector index (ADR-0027 D-8, extended by ADR-0072); the only lexical signal is a ripgrep term-frequency count. - **Keyword rerank blend (ADR-0072, optional):** this fires only WHEN `keywords:` are provided and touches Layer 2 symbol ordering only (Layer 1 and module ranking stay fan-in). Build two ranked lists over the same in-scope symbols: (1) the existing import fan-in order, and (2) a keyword order by ripgrep term-frequency, counting case-insensitive `rg` matches of the supplied terms across each symbol's cited `file:line` span (sum across terms; ties broken by fan-in). Fuse the two ranks with reciprocal rank fusion: `score(sym) = 1/(k + rank_fanin(sym)) + 1/(k + rank_keyword(sym))` with `k = 60`, then sort by descending score. A symbol with zero keyword hits is absent from list (2) and keeps only its fan-in term, so it can never outrank a symbol that matched. This is ripgrep-only: no embeddings, no vector index, and no persisted keyword index. WHEN no `keywords:` are provided, skip this rule entirely and emit the fan-in-only order unchanged. Under `--explain-ranking`, show each symbol's `rank_fanin`, `rank_keyword` (or `none`), and fused score. - **Typed boundary edges:** detect db/http/queue/cache/external-api call-sites by pattern and record each as `kind | target | file:line`. Do not infer dataflow; record call-sites only. - **No flow-graphs, no embeddings (D-7, D-8):** control/data-flow graphs and any vector/semantic layer are out of v1 scope. Do not add them. - **Mermaid diagram emit (optional, ADR-0047):** when a diagram flag is set, render the ALREADY-EXTRACTED edges as Mermaid text appended to MAP.md. `diagram` renders module import adjacency and invoke edges as a flowchart (transitive-reduced, node-capped; collapse to module level above the cap rather than dumping). `sequence:` orders the extracted invoke and boundary edges for one named flow into a sequenceDiagram. This renders extracted edges only; it does not compute a control or data-flow graph (D-7/D-8 hold) and carries the grep-seed framing (a seed to verify; ripgrep is weakest on dynamic dispatch and async, so a sequence may be incomplete). - **Exemplar retrieval (optional, W-18):** when `exemplars` is set, surface 1 to 3 blessed in-repo reference snippets (each a real file:line) an implementer should mirror for a slice with no internal precedent, chosen by import fan-in and convention fit. This is "copy this concrete in-repo pattern", distinct from `stack-currency-check` (external framework currency); the implementer cites the chosen exemplar in slice notes. - **Human HTML projection (optional, ADR-0057 D-3):** when `html` is set, also write `MAP.html`, a single self-contained interactive HTML file (graph data and rendering inline; prefer no view-time external network dependency) into the gitignored `.code-context-map/` folder. It renders the ALREADY-EXTRACTED module/import edges (and, for `chain:` scope, the seed-anchored import chain) as a directed node-link graph with zoom, filter, hover-highlight, and click-to-open; node-cap large graphs (collapse to module level above the cap) so it stays readable. Regenerate on invoke like MAP.md (byte-identical yields `NO_OP`). It renders extracted edges and is a navigation seed, not authoritative (D-7/D-8 still hold), and lives only in the gitignored folder per the D-1 rule above. - **Grep-seed framing:** the artifact must state that it orients the reader and that `grep`/reading the cited `file:line` is the source of truth; the code wins over the map on any disagreement. - **Honesty about extraction limits:** ripgrep heuristics can miss dynamic imports, re-exports, and aliased calls. Record this in the artifact's limitations section; never present the map as exhaustive. - Do not fabricate files, symbols, imports, or boundary edges. Every entry must trace to a real `file:line` in the target codebase. - Cross-link policy: when a task is active, `SOURCE_OF_TRUTH.md` gets at most one `## Code context map` section with a single pointer to the artifact path. Do not duplicate map content into task memory. - Treat task-memory write policy per `WORKFLOW_OPERATING_SYSTEM.md`: `PROPOSED` in Ask/Plan mode, `APPLIED` only in Agent … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Mozurok](https://github.com/Mozurok) - **Source:** [Mozurok/fhorja.dev](https://github.com/Mozurok/fhorja.dev) - **License:** MIT - **Homepage:** https://fhorja.dev Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-mozurok-fhorja-dev-code-context-map - Seller: https://agentstack.voostack.com/s/mozurok - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.