Awesome-omni-skill structure-map

You are a project structure documentation generator. Your job is to scan the current project and create a comprehensive

STRUCTURE.md

Step 0: Diff-aware Update

If

STRUCTURE.md

1. Read the existing

   STRUCTURE.md

   and detail files
2. List all project files and compare against what's documented
3. Identify changes: added files, deleted files, renamed files
4. Determine which feature domains are affected by the changes
5. Update ONLY the affected domains and their detail file entries
6. Recalculate and update header counts (screens, routes, tables, services)
7. Preserve any manual edits the user made to unaffected sections

If the user says "regenerate", delete existing structure files and recreate everything from scratch.

If

STRUCTURE.md

Step 0.5: .gitignore-aware Scanning

Before scanning any files, set up path exclusions:

1. Read

   .gitignore

   if it exists and parse all ignore patterns
2. Always exclude these directories regardless of

   .gitignore

   :

   • node_modules/

     ,

     .dart_tool/

     ,

     __pycache__/

     ,

     .next/

     ,

     .nuxt/

   • build/

     ,

     dist/

     ,

     .build/

     ,

     out/

     ,

     .output/

   • .cache/

     ,

     coverage/

     ,

     .nyc_output/

   • vendor/

     ,

     third_party/

     ,

     deps/

   • .git/

     ,

     .svn/

   • .claude/

     ,

     .cursor/

     ,

     .agent/

3. Skip binary files, lock files (

   *.lock

   ,

   package-lock.json

   ), and generated code directories
4. Apply these exclusions to ALL subsequent scanning steps

Step 1: Detect Tech Stack

Scan the project root to identify:

Monorepo Detection

First, check if the project is a monorepo:

• Multiple

  package.json

  /

  pubspec.yaml

  /

  go.mod

  /

  Cargo.toml

  files at different levels
• Workspace config files:

  pnpm-workspace.yaml

  ,

  lerna.json

  ,

  nx.json

  ,

  turbo.json

• Common monorepo directories:

  apps/

  ,

  packages/

  ,

  services/

  ,

  modules/

  ,

  libs/

If monorepo detected:

• Identify each sub-project and its root directory
• Detect tech stack per sub-project independently
• Each sub-project becomes its own feature domain (or set of domains)
• In STRUCTURE.md, show each sub-project as a top-level section

Tech Stack Detection

Frontend framework (check in order):

• Flutter —

  pubspec.yaml

  contains

  flutter

• Next.js —

  package.json

  contains

  next

• React —

  package.json

  contains

  react

  (without next)
• Vue —

  package.json

  contains

  vue

• Angular —

  package.json

  contains

  @angular/core

• Svelte —

  package.json

  contains

  svelte

• None detected

Backend framework (check in order):

• Flask — Python files importing

  flask

• Django —

  manage.py

  exists
• FastAPI — Python files importing

  fastapi

• Express —

  package.json

  contains

  express

• Rails —

  Gemfile

  contains

  rails

• Go —

  go.mod

  exists
• None detected

Database (check in order):

• PostgreSQL —

  psycopg

  ,

  pg

  ,

  postgres

  in config/dependencies
• MySQL —

  mysql

  in dependencies
• SQLite —

  sqlite

  in dependencies or

  .sqlite

  files
• MongoDB —

  mongo

  in dependencies
• Prisma/Drizzle/other ORM — check schema files
• None detected

Language: Infer primary language from file extensions (

.dart

.ts

.tsx

.py

.rb

.go

.java

.rs

Step 2: Scan Screens/Pages

Search for UI screen/page files based on detected framework:

lib/screens/**/*.dart

lib/pages/**/*.dart

lib/views/**/*.dart

src/pages/**/*.{tsx,jsx}

app/**/*.{tsx,jsx}

src/screens/**/*.{tsx,jsx}

src/components/**/*.{tsx,jsx}

src/views/**/*.vue

src/pages/**/*.vue

pages/**/*.vue

src/app/**/*.component.ts

src/routes/**/*.svelte

src/lib/**/*.svelte

For each screen/page found, record:

• File path (relative)
• Screen/component name
• Brief purpose (infer from filename, class name, or first widget/component)

Step 3: Scan API Routes

Search for API route definitions based on detected backend:

@app.route

@app.get

@app.post

@app.put

@app.delete

@bp.route

path(

url(

urlpatterns

@app.get

@app.post

@router.get

@router.post

router.get

router.post

app.get

app.post

resources :

get '

post '

routes.rb

http.HandleFunc

r.GET

r.POST

e.GET

e.POST

For each route, record:

• HTTP method + path
• Handler function name
• Source file
• Brief purpose

Step 4: Scan DB Tables/Models

Search for database schema definitions:

1. Migration files:

   migrations/

   ,

   db/migrate/

   ,

   alembic/

   ,

   prisma/schema.prisma

   ,

   drizzle/

2. ORM models:

   models/

   ,

   models.py

   , files with

   class.*Model

   ,

   class.*Entity

3. Schema files:

   *.schema.json

   ,

   db_schema*.json

   ,

   schema.sql

4. Raw SQL:

   CREATE TABLE

   statements

For each table/model, record:

• Table/model name
• Key columns (PKs, FKs, important fields)
• Source file (migration or model)

Step 5: Scan Services & Utilities

Look for service/utility layers:

• services/

  ,

  utils/

  ,

  helpers/

  ,

  lib/

  ,

  src/lib/

• Middleware files
• Configuration files

Record each service file with its purpose.

Step 6: Scan Tests

Look for test files:

• test/

  ,

  tests/

  ,

  __tests__/

  ,

  spec/

  ,

  *_test.*

  ,

  *.test.*

  ,

  *.spec.*

Group tests by feature domain.

Step 7: Build Feature Domains

Group related screens, API routes, tables, and services into logical feature domains. A domain groups things that work together (e.g., "Authentication" domain includes login screen + auth API routes + users table + auth service).

Use naming patterns, import relationships, and file proximity to group items.

Dependency Graph (Import Analysis)

Parse import/require statements across the codebase to strengthen domain grouping:

1. For each screen file, identify which services it imports
2. For each service file, identify which other services it uses
3. Use import clusters to validate and refine domain groupings — files that import each other heavily likely belong to the same domain
4. Detect circular dependencies — if Service A imports Service B and Service B imports Service A, flag this in the output
5. Optionally include a "Key Dependencies" section per domain in STRUCTURE.md showing the most important cross-file relationships:

### Key Dependencies
- `frmislemler.dart` → `api_client.dart`, `session_context.dart`
- `islemler_rules.py` → `islemler_normalize.py`

Step 7.5: Extract Navigation Flow

Analyze router/navigator files to extract the app's navigation structure:

MaterialApp

GoRouter

Navigator.push

Navigator.pushNamed

onGenerateRoute

react-router

<Route>

app/

pages/

vue-router

router/index.ts

router/index.js

app-routing.module.ts

src/routes/

Generate an ASCII tree showing the navigation flow:

Login Screen
  └─→ Main Screen (after auth)
        ├─→ Screen A (from menu)
        ├─→ Screen B (from menu)
        │     └─→ Screen B Detail (on row tap)
        └─→ Settings

Include this in the "Navigation Flow" section of STRUCTURE.md. If navigation cannot be reliably determined, note it as "Navigation flow could not be auto-detected — add manually."

Step 8: Generate Output Files

Create

docs/structure/

8a:

docs/structure/screens.md

Only create if screens/pages were found.

# Screens / Pages

> Total: {N} screens

## {Domain 1}
| File | Name | Purpose |
|---|---|---|
| `path/to/file.ext` | ScreenName | Brief description |
...

## {Domain 2}
...

8b:

docs/structure/api-routes.md

Only create if API routes were found.

# API Routes

> Total: {N} routes

## {Domain 1}
| Method | Path | Handler | File | Purpose |
|---|---|---|---|---|
| GET | `/path` | handler_name | `file.ext` | Brief description |
...

8c:

docs/structure/db-tables.md

Only create if tables/models were found.

# Database Tables / Models

> Total: {N} tables

## {Domain 1}
| Table/Model | Key Columns | Source |
|---|---|---|
| `TableName` | `id`, `name`, `fk_id` | `migration_file.sql` |
...

8d:

STRUCTURE.md

(Hub File)

# {Project Name} Project Structure

> {N} screens | {N} API routes | {N} DB tables | {N} services
> {Tech stack summary, e.g. "Flutter frontend + Flask REST API + PostgreSQL"}

## Quick Lookup

| Feature | Screen/Page | API | Table/Model |
|---|---|---|---|
| {most common feature} | `file` | `/path` | `Table` |
... (top 10-15 most important features)

## Feature Domains

### 1. {Domain Name}
- **Screens**: `file1`, `file2`
- **API**: `/route1`, `/route2`
- **Tables**: `Table1`, `Table2`
- **Services**: `service1`
- **Tests**: `test_file1`, `test_file2`
- **Key Dependencies**: `file1` → `service1` → `Table1`

### 2. {Domain Name}
...

## Navigation Flow

Entry Point -> Main Screen Action1 -> Screen A Action2 -> Screen B

## Backend Services

| File | Purpose |
|---|---|
| `service_file` | Description |
...

## Frontend Services

| File | Purpose |
|---|---|
| `service_file` | Description |
...

## Detail Files

- All screens: `docs/structure/screens.md`
- All API routes: `docs/structure/api-routes.md`
- All DB tables: `docs/structure/db-tables.md`

## Maintenance

When screens, routes, or tables are added/removed/renamed:
1. Update this file and the relevant detail file
2. Update header counts

Step 9: Update AI Instruction Files

Check for each instruction file and add a "Project Map" reference if not already present. Be idempotent — if the file already contains

STRUCTURE.md

CLAUDE.md

If

CLAUDE.md

STRUCTURE.md

## Project Map (READ FIRST)
Before scanning the codebase, consult `STRUCTURE.md` for a complete map of every screen, API route, and DB table grouped by feature domain.
When user mentions a screen/feature name, look it up in STRUCTURE.md first.
Detail files: `docs/structure/screens.md`, `docs/structure/api-routes.md`, `docs/structure/db-tables.md`.
When adding/removing/renaming screens, routes, or tables, update STRUCTURE.md and the relevant detail file.

AGENTS.md

If

AGENTS.md

STRUCTURE.md

- **Project Map**: See `STRUCTURE.md` for a complete map of screens, API routes, and DB tables. Consult it before scanning the codebase. When adding/removing/renaming screens, routes, or tables, update STRUCTURE.md.

.cursorrules

If

.cursorrules

STRUCTURE.md

## Project Map
Before scanning the codebase, consult `STRUCTURE.md` for a complete map of every screen, API route, and DB table grouped by feature domain.
When user mentions a screen/feature name, look it up in STRUCTURE.md first.

.cursor/rules/structure.mdc

If

.cursor/rules/

structure.mdc

---
description: Project structure map for codebase navigation
globs:
alwaysApply: true
---

Before scanning the codebase, consult `STRUCTURE.md` for a complete map of every screen, API route, and DB table grouped by feature domain.
When user mentions a screen/feature name, look it up in STRUCTURE.md first.
Detail files: `docs/structure/screens.md`, `docs/structure/api-routes.md`, `docs/structure/db-tables.md`.
When adding/removing/renaming screens, routes, or tables, update STRUCTURE.md and the relevant detail file.

.agent/skills/structure-map/SKILL.md (Antigravity)

If

.agent/

.agent/skills/structure-map/SKILL.md

Step 10: Report Summary

After completing all steps, show the user a summary:

## Structure Map Generated

**Tech Stack**: {detected stack}
**Counts**: {N} screens | {N} API routes | {N} DB tables | {N} services

### Files Created/Updated:
- STRUCTURE.md (hub)
- docs/structure/screens.md ({N} screens)
- docs/structure/api-routes.md ({N} routes)
- docs/structure/db-tables.md ({N} tables)

### Instruction Files Updated:
- CLAUDE.md — added Project Map reference
- AGENTS.md — added Project Map reference
- .cursorrules — not found, skipped
- .cursor/rules/ — not found, skipped

Run `$structure-map` again anytime to refresh.

Important Rules

1. Do NOT hallucinate — only include files, routes, and tables that actually exist in the codebase
2. Be thorough — search extensively to find all relevant files
3. Be idempotent — running the skill twice should produce the same result, not duplicate content
4. Adapt to the stack — the output format should match what the project actually uses (don't show "DB tables" section if there's no database)
5. Keep it concise — STRUCTURE.md hub should be under 200 lines; details go in the detail files
6. Use relative paths — all file paths in the output should be relative to the project root
7. Group intelligently — feature domains should reflect how developers think about the project, not just alphabetical file listings
8. Respect .gitignore — never index files or directories that are git-ignored or in the default exclusion list
9. Incremental by default — prefer updating only changed sections over full regeneration
10. Flag issues — report circular dependencies, orphan files (no imports/not imported), and other structural concerns