korenko-git/opencode-setup/project-map

Project Map - project map (signatures without implementation)

Set SKILL_DIR to the absolute directory containing this file. Invoke the bundled map generator as python3 "$SKILL_DIR/project_map.py"; never resolve it from the user project.

Why This Exists

When a codebase is large, you cannot pass the whole repository into the context of a model that only does planning (for example, a cloud agent that does not write code and only decides what to change and where). It does not need function bodies - only: which files exist, which classes/functions they contain, what their signatures are, and any top-level docstrings/comments. This is similar to C++ header files (.h): the interface is visible, the implementation is hidden.

The local implementation model then:

1. Reads the map and receives a plan from the planner.
2. Opens the specific required files in full (the map is not a replacement for

reading code; it is a navigator).

1. Writes or edits code.
2. Runs the script again to refresh the map to match the current repository

state - the map must be regenerated after every meaningful structural change (new functions/classes/files), not edited manually.

Structural Overview vs. Architecture Review

• Structural overview answers "what exists and where". Run

python3 "$SKILL_DIR/project_map.py", then provide the generated map as the primary context. Do not infer runtime behavior that the map cannot show.

• Architecture review answers "how the system is organized and behaves".

Start by running python3 "$SKILL_DIR/project_map.py" . --out PROJECT_MAP.md --include-hidden .github,.agents, then read only the key entry points and boundaries needed to trace the requested behavior. This includes CI and local agent configuration while retaining the script's exclusions for .git, dependencies, caches, and generated output. Typical targets include application startup, API/router registration, worker or job dispatch, service orchestration, persistence/repository boundaries, external integrations, frontend route/layout entry points, state/data-fetching boundaries, and backend/frontend integration points.

• Expand file reading only when the map and the already-read boundaries show

that it is necessary to validate a specific dependency, control flow, or architectural claim. The map is a navigator, not a substitute for targeted source inspection.

• Do not read the entire repository sequentially or open every file "for

completeness" when a project map and targeted entry-point/boundary reads are sufficient.

How To Use It

The script is located at "$SKILL_DIR/project_map.py". It is a standalone Python script with no external dependencies (stdlib only: ast, re, os, argparse).

Basic usage:

python3 "$SKILL_DIR/project_map.py" /path/to/project --out PROJECT_MAP.md

Useful options:

Example for a real project with a TypeScript frontend and Python backend:

python3 "$SKILL_DIR/project_map.py" . --out PROJECT_MAP.md \
    --ext .py,.ts,.tsx \
    --exclude .git,node_modules,dist,__pycache__,migrations

To map repository automation or local agent configuration, opt in explicitly:

python3 "$SKILL_DIR/project_map.py" . --out PROJECT_MAP.md \
    --include-hidden .github,.agents

What To Do After Running It

For an architecture review, use this workflow:

• Run `python3 "$SKILL_DIR/project_map.py" <scope> --out PROJECT_MAP.md

--include-hidden .github,.agents` first, using the repository root or the relevant backend/frontend subdirectory as the scope.

• Use the resulting map to identify the smallest set of key entry points and

architectural boundaries relevant to the question.

• Read those files and trace only the behavior required for the review,

following imports, calls, and data flow selectively.

• Report structural facts separately from behavioral findings, assumptions,

boundary violations, coupling, and risks.

1. Check that PROJECT_MAP.md was created in the repository root (or wherever

--out points).

1. Give the entire `PROJECT_MAP.md` file to the cloud planning agent as the

primary structural context. There is no need to restate the structure in plain text separately; the file is already in the right format.

1. When the local model changes the code (new/removed functions, classes, or

files), rerun the same script with the same parameters so that PROJECT_MAP.md is overwritten and reflects the current state. Do not edit the map by hand - it is always regenerated.

1. If the map becomes too large (hundreds of files), narrow the scope via

--ext (for example, only .py) or generate maps for subfolders separately (python3 "$SKILL_DIR/project_map.py" backend/ --out backend_map.md, python3 "$SKILL_DIR/project_map.py" frontend/ --out frontend_map.md).

What It Supports

• Python (`.py`) - precise parsing via ast: top-level imports, classes

(base classes, docstring, annotated fields), methods and functions (decorators, annotated parameters with default values, return type, async, first-line/truncated docstring). The function body is always replaced with ....

• JS/JSX/TS/TSX - best-effort parsing via regular expressions with bracket

nesting awareness: function, arrow functions in const/let/var, classes and their methods (static/async/private/... modifiers), export/export default. This is not a full AST parser, so very unusual syntax (TS decorators, generics with nested braces inside types, etc.) may be parsed imperfectly. In that case, the line may simply be omitted from the map; the file's presence in the tree is still preserved.

• Other text files - included in the tree with line count and size; content

is not included.

• Binary files (images, fonts, archives, etc.) - included only in the

tree, marked as [binary file].

• Symbolic links - excluded from both the tree and signature output; the

generator never follows links outside (or back into) the requested project.

Limitations (Important For The Planner)

• This is not a replacement for reading code - the map does not include

function bodies, logic, conditions, or loops. It answers "what exists and where", not "how it works internally".

• The JS/TS parser is regex-based, not AST-based, so it does not guarantee

100% accuracy for every syntax form (for example, nested template strings with braces inside ${...} may confuse nesting depth in rare cases).

• For very large monorepos, generate the map in parts (see item 4 above) or

narrow --ext; otherwise even signatures may consume too many tokens.