code-map

Code Map Generator Skill

Output: .codemap.yaml at repository root Format: YAML — optimized for AI token efficiency Version: 1.0

� Philosophy: Produce a compact, accurate, machine-readable map of the entire codebase that lets an AI agent skip exploratory scanning and jump straight to productive work.

---

When to Use This Skill

✅ Initial onboarding — no .codemap.yaml exists yet ✅ After major structural changes — new projects, controllers, services added/removed ✅ Periodic refresh — the extension flagged the map as stale ❌ Minor code changes within existing files (the map is structural, not line-level)

---

Generation Procedure

Follow these steps in order. Do not skip steps. Do not guess — verify by reading actual files.

Step 1: Discover Solution Structure

1. Read the solution file (*.slnx or *.sln) at the repo root
2. List every project with its path, type (web-mvc, web-api, test, library), and target framework
3. Identify the entry point (Program.cs) for each non-test project

Step 2: Map Directory Purposes

For every project directory (not test projects), scan the top-level subdirectories and assign a one-line purpose. Focus on directories containing source code:

• Controllers/ — what kind of controllers?
• Services/ — business logic for what domain?
• Repositories/ — data access for what entities?
• Models/, DTOs/, Requests/, Responses/ — what data shapes?
• Views/ — what UI areas?
• wwwroot/js/, wwwroot/css/ — frontend assets

Also map significant nested directories (e.g., Views/NewContracts/_ProductPartials/).

Step 3: Extract API Endpoints

For each API controller (files in Controllers/ with [ApiController] attribute):

1. Read the file
2. Extract the class name, base route ([Route("...")])
3. List every action method with its HTTP verb, route, and a brief purpose
4. Use the compact format: "GET /route → description"

Step 4: Extract MVC Controllers

For each MVC controller (controllers returning views, not API):

1. Read the file
2. List key action methods that serve pages or HTMX partials
3. Note which views/partials they load

Step 5: Catalog Services

For each service class (in Services/ directories):

1. Record name, file path, one-line purpose
2. List interface dependencies (constructor parameters)
3. Focus on public methods — what operations does this service expose?

Step 6: Catalog Key Models

For important models only (not every DTO — focus on core domain objects):

• Session state models (e.g., UserSessionData, WizardState, BundleSelections)
• Core domain DTOs (e.g., ContractModel, AccountInfoDto, OrderSummaryDto)
• Request/response objects for major endpoints
• ViewModels used by MVC controllers

Record: name, path, type (entity/dto/viewmodel/session/config), key properties.

Step 7: Map Relationships

Identify the most important relationships by reading DI registrations (Program.cs) and constructor dependencies:

• Controller → Service → Repository chains
• Service → Service dependencies
• Session state flow (who reads/writes session data)
• View loading chains (controller → view → partials)

Use the format: from → to (type: manages|calls|depends|implements) + note

Step 8: Document Cross-Cutting Concerns

Scan Program.cs and middleware configuration to identify:

• Authentication: What schemes? (JWT, Cookie, OAuth)
• Caching: What strategy? (Redis, IMemoryCache, read-through)
• Session: How is session state managed?
• Error handling: Global error handling approach
• Logging: Logging framework and patterns
• Background tasks: Any hosted services or background workers

Step 9: Extract Conventions

Review 3–5 files of each type (controllers, services, repositories) and note patterns:

• DI style (primary constructor vs field injection)
• Async patterns (CancellationToken usage)
• Naming conventions (file naming, class naming, route naming)
• Code organization (regions, file-scoped namespaces)
• Frontend patterns (JS module style, CSS methodology, view loading)

Step 10: Assemble and Write

Combine all collected data into the YAML schema below and write to .codemap.yaml at the repository root. If the file already exists, overwrite it completely.

---

Output Schema

# .codemap.yaml — AI-optimized codebase intelligence map
# Generated by the code-map skill. Do not edit manually.
# Regenerate by invoking the code-map skill.

version: 1
generated: "YYYY-MM-DDTHH:MM:SSZ"

overview:
  name: "repository-name"
  purpose: "one-line description of what this codebase does"
  tech:
    - "framework/language"
  architecture: "one-line data flow description"

projects:
  ProjectName:
    path: "relative/path/"
    type: web-mvc | web-api | test | library
    framework: "net10.0"
    purpose: "what this project does"
    entry: "Program.cs"

directories:
  "relative/path/to/dir/": "one-line purpose"

endpoints:
  - controller: ClassName
    path: "relative/file/path.cs"
    base: "/api/route"
    methods:
      - "VERB /route → brief description"

mvc_controllers:
  - controller: ClassName
    path: "relative/file/path.cs"
    actions:
      - "ActionName → description (view: _ViewName.cshtml)"

services:
  - name: ClassName
    path: "relative/file/path.cs"
    purpose: "what this service does"
    depends: ["IDependency1", "IDependency2"]

models:
  - name: ClassName
    path: "relative/file/path.cs"
    type: entity | dto | viewmodel | session | config
    key_props: ["Property1", "Property2"]

relationships:
  - from: "SourceClass"
    to: "TargetClass"
    type: manages | calls | depends | implements
    note: "brief explanation"

cross_cutting:
  auth: "description of auth strategy"
  cache: "description of caching strategy"
  session: "description of session management"
  error: "description of error handling"
  logging: "description of logging approach"
  background: "description of background tasks"

conventions:
  - "convention description"

---

Quality Criteria

Before writing the file, verify:

• Every non-test project in the solution is listed under projects:
• Every API controller has its endpoints listed with correct HTTP verbs and routes
• Every MVC controller has its key actions listed
• Every service class is cataloged with its purpose and dependencies
• Core models (session state, domain DTOs, ViewModels) are listed with key properties
• Directories section covers all major source directories (not test/config)
• Relationships capture the main dependency chains (controller → service → repo)
• Cross-cutting section addresses auth, cache, session, error handling at minimum
• Conventions lists at least 5 observable patterns
• No file paths are guessed — every path was verified by reading the file system
• YAML is valid — proper indentation, quoting of special characters, no tabs

---

Token Budget Guidelines

Aim for 5,000–10,000 tokens in the output file. To stay within budget:

• Use terse descriptions (5–15 words per item)
• Use the compact endpoint format ("GET / → description")
• Only list key properties on models (3–6 per model, not every field)
• Only list important relationships (major dependency chains, not every DI registration)
• Omit test projects from directories: and services: sections
• Omit generated/vendor files (node_modules/, wwwroot/lib/)

---

END OF SKILL