Merge branch 'main' into copilot/split-tool-impl-layers

nathanjmcdougall · web-flow · commit d10cccafd89d · 2026-03-11T15:28:30.000+13:00
diff --git a/.agents/skills/usethis-python-module-layout-modify/SKILL.md b/.agents/skills/usethis-python-module-layout-modify/SKILL.md
@@ -0,0 +1,12 @@
+---
+name: usethis-python-module-layout-modify
+description: Modify the Python module layout (create, move, rename, or delete modules)
+compatibility: usethis, Python
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# Modifying the module layout for Python projects
+
+Make sure to adhere to the Import Linter checks using the `usethis-qa-import-linter` skill.
diff --git a/.agents/skills/usethis-qa-import-linter/SKILL.md b/.agents/skills/usethis-qa-import-linter/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: usethis-qa-import-linter
+description: Use the Import Linter software on the usethis project
+compatibility: usethis, Python, import-linter
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# Import Linter
+
+## About
+
+Import Linter is a static analysis tool to enforce a self-imposed architecture on imports. It allows you to define rules about how different parts of your codebase can import each other, helping to maintain a clean and organized code structure.
+
+## Usage
+
+```bash
+uv run lint-imports
+```
+
+## Configuration File
+
+This project uses the `.importlinter` INI file to configure Import Linter. You specify _contracts_ which need to be complied with between modules' imports. For the `usethis` project, we mainly use the `layers` contract: earlier listed "higher" layers are not allowed to import from any "lower" layers. 
+
+### Example Structure
+
+Where `xyz` is the name of the root package (i.e. `usethis` for this project):
+
+```ini
+[importlinter]
+root_packages =
+    xyz
+
+[importlinter:contract:xyz]
+name = xyz
+type = layers
+containers =
+    xyz
+layers =
+    ui
+    backend
+    domain
+exhaustive = true
+
+[importlinter:contract:core_submodule]
+name = xyz.core.submodule
+type = layers
+containers =
+    xyz.core.submodule
+layers =
+    layer1
+    layer2
+exhaustive = true
+```
+
+## Procedure
+
+1. Ensure the module structure complies with the Import Linter configuration.
+2. Explicitly add/rename new/modified modules to their parent-level contract (to adhere to the `exhaustive` setting).
+3. For major refactorings, rationalize the module structure and update the Import Linter configuration accordingly.
+4. Run Import Linter to verify that all contracts are satisfied.
diff --git a/.agents/skills/usethis-qa-static-checks/SKILL.md b/.agents/skills/usethis-qa-static-checks/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: usethis-qa-static-checks
 description: Perform static code checks
-compatibility: prek, basedpyright
+compatibility: usethis, Python, prek, basedpyright
 license: MIT
 metadata:
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Static Checks
