code-map git:20260402.7705868A

Immutable. This exact content is served forever at /api/v1/blob/1851af4e699de270.

---
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

```yaml
# .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**