project-setup

Onboarding

Step 1: Orientation

1. Read README.md for purpose and setup
2. Check for AGENTS.md, CONTRIBUTING.md
3. Look at directory structure
4. Check requirements.in / requirements.txt / pyproject.toml for dependencies
5. Check Makefile or justfile for common commands

Step 2: Identify the Stack

• Framework: Dagster, Solara, Streamlit, FastAPI, Django, Flask
• Database: PostgreSQL, SQLite, Redis
• Testing: pytest (check conftest.py for fixtures)
• Linting: ruff, flake8, pylint
• Type checking: mypy, pyright
• Dependency management: pip-compile, poetry, uv

Step 3: Map Architecture

1. Find entry points (__main__.py, CLI commands, app factory, pipeline definitions)
2. Trace data flow from input to output
3. Identify data models (dataclasses, Pydantic, ORM models)
4. Note external integrations (APIs, databases, message queues)
5. Check configuration (env vars, settings files)

Step 4: Get It Running

1. Create and activate virtual environment: python -m venv .venv && source .venv/bin/activate
2. Install dependencies: pip install -r requirements.txt
3. Set up env vars (check .env.example)
4. Start required services (database, etc.)
5. Run tests: pytest
6. Run the application

Step 5: Update AGENTS.md

After understanding the project, ensure AGENTS.md captures:

• Project description
• Directory structure
• Build, test, lint commands
• Code conventions
• Dependency management workflow

Health Indicators

| Indicator | Healthy | Needs attention | |------------------|-----------------------------|------------------------------| | Tests | Pass, good coverage | No tests or failures | | Type hints | On all public functions | Missing or incomplete | | Dependencies | Pinned, no known CVEs | Outdated with vulnerabilities| | Linting | ruff/mypy pass cleanly | Warnings ignored | | Docs | README current, docstrings | README contradicts code |

When to Use

Load this skill when starting work on a new or unfamiliar Python project.