code-map

name	code-map
description	Generate an AI-optimized YAML code map (.codemap.yaml) at the repository root. The map captures project structure, API surface, services, models, relationships, and conventions so that AI agents can quickly navigate and understand the codebase without cold-start exploration. Invoke this skill to create or regenerate the 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