project-map

Project Map Skill

Generate .agentic/project-map.md to orient any agent to the codebase.

Step 0 — Check Existing Map

Check if .agentic/project-map.md already exists:

• If present: Ask the user if they want to refresh it or keep existing.
  • Default: keep existing unless --refresh flag is passed or user explicitly requests refresh.
• If absent: Continue to Step 1.

Step 1 — Auto-discover Codebase Structure

Detect the language and architecture by inspecting the filesystem:

1. Detect language(s) — inspect for manifest files:

   • go.mod → Go
   • package.json / tsconfig.json → TypeScript/JavaScript
   • pyproject.toml → Python
   • composer.json → PHP

2. Detect architecture markers — inspect directory names:

   • Hexagonal: domain/, application/, infrastructure/, ports/
   • CQRS: command/, query/
   • DDD: aggregate roots, value objects, domain events

3. Read build/test/lint commands — inspect:

   • Makefile
   • justfile
   • package.json scripts
   • Taskfile.yml

4. Identify entry points — look for:

   • main.go
   • cmd/
   • src/index.ts
   • app/main.py
   • artisan
   • bin/

5. For monorepos — detect tier structure from .agentic/config.yaml if present.

Step 2 — Map the Layer Structure

1. Identify architectural layers:

   • Domain: entities, value objects, domain events, repository interfaces
   • Application: use cases, command/query handlers
   • Infrastructure: repository implementations, HTTP clients, messaging adapters
   • Ports/Adapters: HTTP controllers, CLI commands, message consumers

2. List key modules/packages (top 5-10) with one-line purpose each.

3. Note non-obvious conventions:

   • Naming rules (e.g., *_test.go suffix, service.go patterns)
   • File organization (co-location rules, split by concern vs. feature)
   • Error handling patterns
   • Token/entity naming conventions

Step 3 — Identify Complexity Hotspots

1. Largest files by line count — use wc -l or equivalent on key source files.