TARE-Learn/deliverables/ai-engineering-skills-delivery/skills/project-knowledge-builder/references/compatibility.md

Cross-Platform Compatibility

Use this reference when running or installing the skill on macOS, Windows, Linux, or CI.

Compatibility Summary

Area	macOS	Linux	Windows
SKILL.md workflow	Supported	Supported	Supported
project_inventory.py	Supported with Python 3.9+	Supported with Python 3.9+	Supported with Python 3.9+
Python dependencies	Standard library only	Standard library only	Standard library only
Path handling	pathlib	pathlib	pathlib
Shell dependency	None in script	None in script	None in script
Generated Markdown paths	POSIX-style relative paths	POSIX-style relative paths	POSIX-style relative paths

The script intentionally emits repository-relative paths with / separators so generated Markdown is stable across platforms and friendlier for URLs, GitHub, and RAG metadata.

Python Invocation

macOS and Linux usually have one of these:

python3 skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated

Windows PowerShell usually uses:

py -3 skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated
python skills\project-knowledge-builder\scripts\project_inventory.py --root . --out docs\project-knowledge\generated

CI should prefer an explicit Python:

python -m py_compile skills/project-knowledge-builder/scripts/project_inventory.py
python skills/project-knowledge-builder/scripts/project_inventory.py --root . --out docs/project-knowledge/generated --json

Command Substitutions

Task	macOS/Linux	Windows PowerShell
List docs	find docs/project-knowledge -type f | sort	Get-ChildItem docs/project-knowledge -Recurse -File | Sort-Object FullName
Search placeholders	`rg -n "TODO	TBD" docs/project-knowledge`
Show git status	git status --short	git status --short
Remove temp output	rm -rf ./kb-inventory	Remove-Item .\kb-inventory -Recurse -Force

rg is preferred where available. If rg is not installed, use the platform search available in the environment.

Avoid In Skill Examples

• Hard-coded /tmp paths when the command should work on Windows.
• POSIX-only command chains such as cmd1 && cmd2 in user-facing instructions when a PowerShell equivalent is needed.
• Shell glob assumptions that behave differently between zsh, bash, PowerShell, and cmd.
• Python code that depends on executable shebang behavior; Windows users should call py -3 script.py.

Known Limits

• Java endpoint extraction is regex-based and intentionally conservative. It does not fully resolve constants, composed annotations, or inherited controller mappings.
• SQL table extraction looks for CREATE TABLE; tables created dynamically or through migrations in another DSL need manual documentation.
• Frontend route extraction scans route-like literals and view files; runtime-generated route data from APIs still requires backend menu/permission data or database export.
• Very large repositories may need --max-files tuning or additional ignore directories.