Project layout

Applies Sun Lab conventions for project directory structure across all five project archetypes.

You MUST read this skill before creating, restructuring, or verifying any Sun Lab project's directory layout. You MUST verify your changes against the checklist before submitting.

Scope

Covers:

• •Project directory trees for all five Sun Lab archetypes
• •Common root files and their purposes
• •Environment directories (envs/) with OS-specific files
• •Test directory conventions (tests/ vs test/)
• •Documentation directory placement (defers to /api-docs for internal structure)
• •.github/ directory structure
• •Archetype identification criteria

Does not cover:

• •File-level ordering within source files (see /python-style, /cpp-style, /csharp-style)
• •Documentation file contents and Sphinx configuration (see /api-docs)
• •pyproject.toml structure and fields (see /pyproject-style)
• •README file contents (see /readme-style)
• •Code style or formatting rules (see language-specific style skills)

Workflow

You MUST follow these steps when this skill is invoked.

Step 1: Identify the project archetype

Determine which archetype applies using this table:

Step 2: Load the reference tree

Read archetype-trees.md and locate the section matching the identified archetype. The reference tree is the authoritative source for directory structure.

Step 3: Apply conventions

Create or verify the project structure against the reference tree and the rules below. When creating a new project, generate all required directories and files. When verifying, report any deviations from the expected structure.

Step 4: Verify compliance

Complete the verification checklist at the end of this file. Every item must pass before submitting work.

Common root files

These files appear at the root of all (or most) Sun Lab projects:

Python-specific root files

PlatformIO-specific root files

Unity-specific root files

Environment directories

Python projects (Python-only and Python+C++ extension) include an envs/ directory with OS-specific conda/mamba environment files:

envs/
├── {abbr}_dev_lin.yml            # Linux conda environment specification
├── {abbr}_dev_lin_spec.txt       # Linux explicit package list
├── {abbr}_dev_osx.yml            # macOS conda environment specification
├── {abbr}_dev_osx_spec.txt       # macOS explicit package list
├── {abbr}_dev_win.yml            # Windows conda environment specification
└── {abbr}_dev_win_spec.txt       # Windows explicit package list

The {abbr} placeholder is a short project abbreviation (e.g., axa for ataraxis-automation, axbu for ataraxis-base-utilities). Each platform has two files:

• •.yml — human-readable conda environment specification used by mamba env create
• •_spec.txt — explicit package list generated by mamba list --explicit

PlatformIO and Unity projects do NOT have envs/ directories.

Test directories

Python test structure

The tests/ directory mirrors the src/package_name/ subpackage structure:

tests/
├── submodule/
│   └── module_test.py
└── standalone_test.py

PlatformIO test structure

The test/ directory (singular, not tests/) follows PlatformIO's native test convention:

test/
└── test_component.cpp

Documentation directory

All Python and C++ projects include a docs/ directory for Sphinx documentation. For the complete internal structure, Sphinx configuration, and RST templates, invoke /api-docs.

C# Unity projects do NOT have a docs/ directory.

.github/ directory

Python projects include a .github/ directory with issue templates:

.github/
└── ISSUE_TEMPLATE/
    ├── bug_report.md
    └── feature_request.md

PlatformIO and Unity projects may or may not include .github/ depending on whether they are published to GitHub as standalone repositories.

Source directory conventions

Python-only (src/ layout)

src/
└── package_name/
    ├── __init__.py
    ├── module.py
    └── py.typed

Python + C++ extension (src/ flat namespace)

src/
├── c_extensions/
│   └── module_ext.cpp
├── python_wrapper/
│   ├── __init__.py
│   └── wrapper_module.py
├── __init__.py
├── module_ext.pyi
└── py.typed

PlatformIO library (header-only src/)

src/
├── main.cpp                  # Development entry point (excluded from library)
├── primary_header.h
└── shared_assets.h

PlatformIO firmware (src/)

src/
├── main.cpp                  # Firmware entry point (setup/loop)
└── custom_module.h

C# Unity (Assets/)

Assets/
├── TaskName/
│   ├── Configurations/
│   ├── Materials/
│   ├── Prefabs/
│   ├── Scripts/
│   │   └── TaskScript.cs
│   ├── Sounds/
│   └── Textures/
├── Plugins/
└── Scenes/

Related skills

Proactive behavior

You should proactively offer to invoke this skill when:

• •Creating a new Sun Lab project from scratch
• •The user asks where to place a new file or directory
• •A project structure appears to deviate from conventions during exploration
• •The user asks about project directory conventions or archetypes

Verification checklist

You MUST verify your work against this checklist before submitting any layout changes.

Project Layout Compliance:

Archetype Identification:
- [ ] Project archetype correctly identified from key indicators
- [ ] Reference tree loaded from archetype-trees.md

Common Root Files:
- [ ] LICENSE present (GPL-3.0)
- [ ] README.md present
- [ ] .gitignore present
- [ ] CLAUDE.md present
- [ ] Archetype-specific root files present (pyproject.toml, platformio.ini, etc.)

Source Directory:
- [ ] Python projects use src/ layout with package_name/ subdirectory
- [ ] Python+C++ extension uses flat namespace under src/ (c_extensions/, wrapper/, etc.)
- [ ] PlatformIO projects use src/ with header-only .h files
- [ ] Unity projects use Assets/ with task-specific subdirectories

Environment Directory:
- [ ] Python projects have envs/ with 6 files (3 platforms x 2 files each)
- [ ] envs/ file names use correct abbreviation prefix
- [ ] PlatformIO and Unity projects do NOT have envs/

Test Directory:
- [ ] Python projects use tests/ (plural) with _test.py suffix
- [ ] PlatformIO library projects use test/ (singular) with test_ prefix
- [ ] PlatformIO firmware and Unity projects have no dedicated test directory

Documentation Directory:
- [ ] Python and C++ projects have docs/ directory
- [ ] Unity projects do NOT have docs/

GitHub Directory:
- [ ] .github/ISSUE_TEMPLATE/ present for published GitHub repositories

No Duplicates:
- [ ] Directory trees not duplicated in other skills (api-docs owns docs/ internals)
- [ ] File-level ordering not specified (owned by language style skills)