chisel-checker 0.1.2__tar.gz → 0.2.0__tar.gz

chisel_checker-0.2.0/.grimp_cache/af276a573254b22776d0a8d1fe8e976b0694e680.data.json

@@ -0,0 +1 @@
+{"chisel.checker.models.file_info":[["chisel.checker.models.layer",6,"from chisel.checker.models.layer import Layer"],["ast",2,"import ast"],["pathlib",4,"from pathlib import Path"],["dataclasses",3,"from dataclasses import dataclass, field"]],"chisel.checker.models.exemption":[["dataclasses",1,"from dataclasses import dataclass, field"]],"chisel.checker.config":[["pathlib",3,"from pathlib import Path"],["dataclasses",2,"from dataclasses import dataclass, field"]],"chisel.checker.errors":[],"chisel.checker.models":[["chisel.checker.models.file_info",3,"from chisel.checker.models.file_info import FileInfo"],["chisel.checker.models.violation",9,"from chisel.checker.models.violation import Violation"],["chisel.checker.models.layer",5,"from chisel.checker.models.layer import Layer"],["chisel.checker.models.severity",8,"from chisel.checker.models.severity import Severity"],["chisel.checker.models.import_edge",4,"from chisel.checker.models.import_edge import ImportEdge"],["chisel.checker.models.project_info",6,"from chisel.checker.models.project_info import ProjectInfo"],["chisel.checker.models.exemption",2,"from chisel.checker.models.exemption import Exemption"],["chisel.checker.models.result",7,"from chisel.checker.models.result import CheckResult"]],"chisel.checker.reporter":[["rich",6,"from rich.console import Console"],["json",2,"import json"],["chisel.checker.rule_metadata",13,"from chisel.checker.rule_metadata import skill_name_for_rule"],["dataclasses",3,"from dataclasses import dataclass"],["rich",7,"from rich.markup import escape"],["chisel.checker.models.result",10,"from chisel.checker.models.result import CheckResult"],["rich",8,"from rich.table import Table"],["typing",4,"from typing import Any"],["chisel.checker.models.violation",12,"from chisel.checker.models.violation import Violation"],["chisel.checker.models.severity",11,"from chisel.checker.models.severity import Severity"]],"chisel.checker.factory":[["chisel",4,"from chisel.checker.controllers.check_controller import CheckController"],["dataclasses",2,"from dataclasses import dataclass, field"],["chisel",14,"from chisel.checker.services.protocols import ICheckerService"],["chisel",7,"from chisel.checker.services.app_file import AppFileService"],["chisel",5,"from chisel.checker.repositories.import_graph import ImportGraph"],["chisel",16,"from chisel.checker.services.structural import StructuralService"],["chisel",9,"from chisel.checker.services.concurrency import ConcurrencyService"],["chisel",12,"from chisel.checker.services.import_boundary import ImportBoundaryService"],["chisel",11,"from chisel.checker.services.error_flow import ErrorFlowService"],["chisel",17,"from chisel.checker.services.suppression import SuppressionService"],["chisel",18,"from chisel.checker.services.check_test_structure import CheckTestStructureService"],["chisel",13,"from chisel.checker.services.project_structure import ProjectStructureService"],["chisel",6,"from chisel.checker.repositories.protocols import IImportGraph"],["chisel",15,"from chisel.checker.services.session import SessionService"],["chisel",10,"from chisel.checker.services.config_startup import ConfigStartupService"],["chisel",8,"from chisel.checker.services.complexity import ComplexityService"]],"chisel.checker.models.import_edge":[["dataclasses",2,"from dataclasses import dataclass"]],"chisel.checker.models.self_update":[["dataclasses",1,"from dataclasses import dataclass"],["enum",2,"from enum import Enum"]],"chisel":[["chisel.checker",2,"from chisel.checker import check_project"]],"chisel.checker.rule_metadata":[],"chisel.checker.models.layer":[["enum",2,"from enum import Enum"]],"chisel.checker":[["chisel.checker.factory",2,"from chisel.checker.factory import CheckerFactory"],["chisel.checker.reporter",3,"from chisel.checker.reporter import Reporter"]],"chisel.checker.models.violation":[["chisel.checker.models.severity",4,"from chisel.checker.models.severity import Severity"],["dataclasses",2,"from dataclasses import dataclass"]],"chisel.checker.models.severity":[["enum",2,"from enum import Enum"]],"chisel.checker.models.project_info":[["dataclasses",2,"from dataclasses import dataclass, field"],["chisel.checker.models.file_info",5,"from chisel.checker.models.file_info import FileInfo"],["pathlib",3,"from pathlib import Path"]],"chisel.checker.models.result":[["dataclasses",2,"from dataclasses import dataclass, field"],["chisel.checker.models.violation",4,"from chisel.checker.models.violation import Violation"]],"chisel.checker.models.agent_skill":[["dataclasses",1,"from dataclasses import dataclass"],["enum",2,"from enum import Enum"]]}

chisel_checker-0.2.0/.grimp_cache/chisel.meta.json

@@ -0,0 +1 @@
+{"chisel.checker.models.import_edge": 1783243922.6667128, "chisel.checker.config": 1783243922.6664708, "chisel.checker.models.violation": 1783243922.6667128, "chisel.checker": 1783243922.6663847, "chisel.checker.models.file_info": 1783243922.6667128, "chisel": 1783243922.6663358, "chisel.checker.models.layer": 1783243922.6667128, "chisel.checker.models.result": 1783243922.6667128, "chisel.checker.models.severity": 1783243922.6667128, "chisel.checker.errors": 1783243922.6665595, "chisel.checker.models.agent_skill": 1783243922.6667128, "chisel.checker.models": 1783243922.6665595, "chisel.checker.models.self_update": 1783243922.6667128, "chisel.checker.models.exemption": 1783243922.6667128, "chisel.checker.models.project_info": 1783243922.6667128, "chisel.checker.rule_metadata": 1783243922.6670513, "chisel.checker.reporter": 1783243922.6667128, "chisel.checker.factory": 1783243922.6665595}

chisel_checker-0.2.0/.grimp_cache/myapp.meta.json

@@ -0,0 +1 @@
+{"myapp": 1783243932.1338243}

{chisel_checker-0.1.2 → chisel_checker-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chisel_checker
-Version: 0.1.2
+Version: 0.2.0
 Summary: Opinionated architecture constraint checker
 Author-email: ChidiRNweke <chidi125@gmail.com>
 Requires-Python: >=3.11
@@ -31,8 +31,10 @@ pip install chisel
 chisel check ./backend              # check a project
 chisel rules                        # list all ~55 rules grouped by category
 chisel explain structural:print-banned  # detailed fix guidance
-chisel check . --json               # machine-readable output for agents
+chisel check . --json               # violations with message refs + skill names
 chisel check . --no-strict          # skip src-layout enforcement
+chisel update self                  # upgrade the installed CLI package
+chisel update skills --target codex # overwrite installed skills with bundled copies
 ```
 
 ## Commands
@@ -40,12 +42,39 @@ chisel check . --no-strict          # skip src-layout enforcement
 | Command | Description |
 |---|---|
 | `chisel check [path]` | Scan a project for architectural violations |
-| `chisel check . --json` | Output violations as structured JSON |
+| `chisel check . --json` | Output violations as structured JSON with deduplicated messages |
 | `chisel check . --strict/--no-strict` | Toggle src-layout and build-config enforcement |
 | `chisel rules` | List all rules, grouped by category |
 | `chisel rules --json` | Machine-readable rule listing |
 | `chisel explain <rule-id>` | Detailed description + fix guidance for a rule |
 | `chisel explain <category>` | All rules in a category (e.g. `structural`) |
+| `chisel setup [path]` | Install Chisel agent skills into a repo for Codex, Claude Code, or OpenCode |
+| `chisel update self` | Upgrade the installed Chisel package |
+| `chisel update skills [path]` | Refresh installed Chisel skills after confirmation |
+
+## Agent skills
+
+Install Chisel's bundled skills into a project so coding agents can load the same architecture guidance that the checker enforces:
+
+```bash
+chisel setup --target codex      # writes .agents/skills/
+chisel setup --target claude     # writes .claude/skills/
+chisel setup --target opencode   # writes .opencode/skills/
+```
+
+Without `--target`, `chisel setup` asks which agent to configure when running interactively. Use `--skill qa` to install one skill, `--dry-run --json` to preview, and `--overwrite` to replace existing skill directories.
+
+Refresh previously installed skills after upgrading Chisel:
+
+```bash
+chisel update skills --target codex
+```
+
+This overwrites local modifications in the selected skill directories, so Chisel asks for confirmation before writing. Use `--yes` in automation and `--dry-run --json` to preview.
+
+Agent-facing JSON output deduplicates repeated violation messages: each
+violation carries `message_ref`, and the top-level `messages` array contains
+each full message once with its `skill_name`.
 
 ## What gets checked
 
@@ -104,4 +133,3 @@ pytest tests/ -q
 ```
 
 The checker is self-validating: `chisel check . --strict` produces zero violations on its own source.
-

{chisel_checker-0.1.2 → chisel_checker-0.2.0}/README.md

@@ -16,8 +16,10 @@ pip install chisel
 chisel check ./backend              # check a project
 chisel rules                        # list all ~55 rules grouped by category
 chisel explain structural:print-banned  # detailed fix guidance
-chisel check . --json               # machine-readable output for agents
+chisel check . --json               # violations with message refs + skill names
 chisel check . --no-strict          # skip src-layout enforcement
+chisel update self                  # upgrade the installed CLI package
+chisel update skills --target codex # overwrite installed skills with bundled copies
 ```
 
 ## Commands
@@ -25,12 +27,39 @@ chisel check . --no-strict          # skip src-layout enforcement
 | Command | Description |
 |---|---|
 | `chisel check [path]` | Scan a project for architectural violations |
-| `chisel check . --json` | Output violations as structured JSON |
+| `chisel check . --json` | Output violations as structured JSON with deduplicated messages |
 | `chisel check . --strict/--no-strict` | Toggle src-layout and build-config enforcement |
 | `chisel rules` | List all rules, grouped by category |
 | `chisel rules --json` | Machine-readable rule listing |
 | `chisel explain <rule-id>` | Detailed description + fix guidance for a rule |
 | `chisel explain <category>` | All rules in a category (e.g. `structural`) |
+| `chisel setup [path]` | Install Chisel agent skills into a repo for Codex, Claude Code, or OpenCode |
+| `chisel update self` | Upgrade the installed Chisel package |
+| `chisel update skills [path]` | Refresh installed Chisel skills after confirmation |
+
+## Agent skills
+
+Install Chisel's bundled skills into a project so coding agents can load the same architecture guidance that the checker enforces:
+
+```bash
+chisel setup --target codex      # writes .agents/skills/
+chisel setup --target claude     # writes .claude/skills/
+chisel setup --target opencode   # writes .opencode/skills/
+```
+
+Without `--target`, `chisel setup` asks which agent to configure when running interactively. Use `--skill qa` to install one skill, `--dry-run --json` to preview, and `--overwrite` to replace existing skill directories.
+
+Refresh previously installed skills after upgrading Chisel:
+
+```bash
+chisel update skills --target codex
+```
+
+This overwrites local modifications in the selected skill directories, so Chisel asks for confirmation before writing. Use `--yes` in automation and `--dry-run --json` to preview.
+
+Agent-facing JSON output deduplicates repeated violation messages: each
+violation carries `message_ref`, and the top-level `messages` array contains
+each full message once with its `skill_name`.
 
 ## What gets checked
 
@@ -89,4 +118,3 @@ pytest tests/ -q
 ```
 
 The checker is self-validating: `chisel check . --strict` produces zero violations on its own source.
-

{chisel_checker-0.1.2 → chisel_checker-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chisel_checker"
-version = "0.1.2"
+version = "0.2.0"
 description = "Opinionated architecture constraint checker"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [
@@ -29,4 +29,7 @@ build-backend = "hatchling.build"
 
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/chisel"]
+packages = ["src/chisel"]
+
+[tool.hatch.build.hooks.custom]
+path = "src/chisel/_build_hooks/skills_hook.py"

chisel_checker-0.2.0/skills/architecting-fullstack/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: architecting-fullstack
+description: Orchestrates full-stack architecture patterns (monorepo, BFF). Triggered when building or reviewing an application spanning frontend and backend, or starting a new project. Decides the pattern and hands off to specialised skills for implementation details.
+---
+
+# Fullstack SWE Skill
+
+This skill decides the architecture and then hands off to the right specialised skills. It does
+not repeat what those skills already cover — read them directly for implementation details.
+
+---
+
+## Blueprint
+
+Read this skill to decide the architecture pattern and project structure. Then read the specialised skills (`building-python-backend`, `building-sveltekit-frontend`, `designing-svelte-ui`) for implementation details on each layer.
+
+Finally, ask the user if they want you to start coding or explicitly invoke the `planning-features` skill to write a detailed plan.
+
+## Monorepo — Always
+
+Every project is a monorepo. Even if there's only a frontend today, the structure accommodates a
+backend tomorrow without reorganising. One repo, one agent context, full 360° visibility.
+
+```
+project-root/
+├── CLAUDE.md                # Project-level context — read first every session
+├── AGENTS.md                # Design system decisions (populated by designing-svelte-ui skill)
+├── .github/                 # CI/CD workflows
+├── docker-compose.yml       # Local dev: frontend + backend + postgres
+├── frontend/                # SvelteKit app
+│   ├── package.json         # pnpm as package manager
+│   ├── pnpm-lock.yaml
+│   ├── svelte.config.js
+│   ├── tsconfig.json
+│   ├── .env                 # Frontend env vars only — never shares secrets with backend
+│   └── src/
+│       ├── app.css
+│       ├── app.html
+│       ├── hooks.server.ts
+│       ├── routes/
+│       └── lib/
+│           ├── api/         # openapi-fetch client + generated schema.d.ts
+│           ├── models/
+│           ├── services/
+│           ├── controllers/
+│           ├── factories/
+│           ├── stores/
+│           └── components/
+│               ├── ui/          # shadcn auto-generated
+│               ├── primitives/  # Themed wrappers
+│               ├── layout/      # Page-level structure
+│               └── domain/      # Feature-specific
+└── backend/                 # Python FastAPI app — src layout
+    ├── pyproject.toml       # Project metadata, dependencies, tool config
+    ├── alembic.ini
+    ├── .env                 # Backend env vars only
+    ├── alembic/
+    │   ├── env.py
+    │   └── versions/
+    ├── tests/
+    │   ├── conftest.py
+    │   ├── unit/
+    │   └── integration/
+    └── src/
+        └── myapp/           # Replace "myapp" with actual project name
+            ├── __init__.py
+            ├── app.py       # FastAPI create_app()
+            ├── config.py    # AppConfig.from_env()
+            ├── factory.py
+            ├── errors.py
+            ├── dependencies.py
+            ├── models/
+            │   └── __init__.py
+            ├── services/
+            │   └── __init__.py
+            ├── repositories/
+            │   ├── __init__.py
+            │   └── orm/
+            │       ├── __init__.py  # Imports all ORM models for Alembic
+            │       └── base.py      # DeclarativeBase
+            ├── controllers/
+            │   └── __init__.py
+            └── routes/
+                └── __init__.py
+```
+
+### Why monorepo, always
+
+- An agent (Claude Code, Cursor, etc.) can see the full stack in one context window
+- Cross-stack changes (backend endpoint + frontend service + UI) happen in one commit
+- Shared `.github/` CI, shared `docker-compose.yml`, shared `CLAUDE.md`
+- No version drift between frontend expectations and backend reality
+
+### Package management
+
+- **Frontend**: pnpm. Use `pnpm` for all commands. `pnpm-lock.yaml` committed.
+- **Backend**: `pyproject.toml` with pip or uv. No `setup.py`, no `requirements.txt`.
+  Use the src layout (`backend/src/myapp/`) so imports are always `from myapp.x import y`.
+
+### Running locally
+
+```yaml
+# docker-compose.yml
+services:
+  db:
+    image: postgres
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: myapp
+      POSTGRES_PASSWORD: myapp
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  backend:
+    build: ./backend
+    env_file: ./backend/.env
+    ports:
+      - "8000:8000"
+    depends_on:
+      - db
+    volumes:
+      - ./backend/src:/app/src # hot reload
+
+  frontend:
+    build: ./frontend
+    env_file: ./frontend/.env
+    ports:
+      - "5173:5173"
+    depends_on:
+      - backend
+    volumes:
+      - ./frontend/src:/app/src # hot reload
+
+volumes:
+  pgdata:
+```
+
+For local dev without Docker, run backend and frontend in separate terminals:
+
+```bash
+# Terminal 1 — backend
+cd backend && uv run uvicorn src.myapp.app:app --reload --port 8000
+
+# Terminal 2 — frontend
+cd frontend && pnpm dev
+```
+
+---
+
+## Step 1: Decide the Architecture
+
+Before writing any code, determine which pattern fits. Both use the monorepo structure above.
+
+### Pattern A — TypeScript Monolith
+
+**Use when:**
+
+- Team is TypeScript-only, no dedicated backend engineers
+- Backend is relatively simple (CRUD, light business logic)
+- Rapid prototyping or early-stage product
+- No existing backend / microservices to integrate with
+
+**Stack:** SvelteKit as the full-stack framework. Server routes / API routes handle
+backend logic. Database accessed directly from the server layer (Drizzle or Prisma).
+The `backend/` folder is omitted or used only for shared scripts/migrations.
+
+**Structure:** Same monorepo, but `backend/` is either absent or minimal:
+
+```
+project-root/
+├── CLAUDE.md
+├── AGENTS.md
+├── frontend/               # SvelteKit handles everything
+│   ├── package.json
+│   └── src/
+│       ├── lib/
+│       │   ├── db/         # Drizzle schema + migrations
+│       │   ├── services/   # Business logic (same layering discipline)
+│       │   └── models/
+│       └── routes/
+└── docker-compose.yml      # Just postgres for local dev
+```
+
+### Pattern B — BFF (Backend-for-Frontend)
+
+**Use when:**
+
+- Separate Python backend already exists or is planned
+- Backend has its own OpenAPI spec
+- Teams split across frontend and backend
+- Business logic is complex enough to warrant a dedicated backend
+- Backend needs to run independently (scheduled jobs, other consumers)
+
+**Stack:** SvelteKit frontend + Python FastAPI backend. Full monorepo structure as shown above.
+
+---
+
+## Step 2: Hand off to Specialised Skills
+
+Once the pattern is decided, the relevant skills take over. Read them fully before writing code.
+
+### Pattern A — TypeScript Monolith
+
+| What you're building              | Read                                                                                         |
+| --------------------------------- | -------------------------------------------------------------------------------------------- |
+| Pages, components, UI             | `designing-svelte-ui` skill — design system first, always                                              |
+| Loaders, actions, stores, routing | `building-sveltekit-frontend` skill — BFF patterns apply here too, minus the openapi layer                    |
+| Database schema + queries         | Use Drizzle. Follow the repository pattern from `building-sveltekit-frontend` — keep DB access out of loaders |
+
+**Key adaptation for Pattern A:** The `building-sveltekit-frontend` skill is written for BFF with a separate
+backend, but the layering discipline is identical. The difference is your "service" calls Drizzle
+directly instead of an openapi-fetch client. Everything else — no business logic in loaders,
+controllers for multi-service orchestration, stores for client state — applies unchanged.
+
+### Pattern B — BFF
+
+| What you're building                        | Read                                   |
+| ------------------------------------------- | -------------------------------------- |
+| Frontend pages, components, UI              | `designing-svelte-ui` skill                      |
+| Frontend loaders, actions, stores           | `building-sveltekit-frontend` skill                     |
+| Backend services, controllers, repositories | `building-python-backend` skill                     |
+| Typed API client (frontend ↔ backend)       | `building-sveltekit-frontend` → `references/openapi.md` |
+
+The contract between frontend and backend is the OpenAPI spec. The backend owns it. The
+frontend generates types from it and never hand-writes API types.
+
+---
+
+## Step 3: Project Setup Checklist
+
+Regardless of pattern, do these before writing features. Copy this checklist into your initial response scratchpad to track your progress:
+
+### Both patterns
+
+- [ ] Verify environment dependencies: ensure `pnpm`, `uv` (or `pip`), and `docker` are installed. Fail gracefully with instructions if they are missing.
+- [ ] Monorepo structure created as shown above
+- [ ] `CLAUDE.md` at project root (see below)
+- [ ] `AGENTS.md` at project root with design system decisions (populated by `designing-svelte-ui` skill)
+- [ ] `docker-compose.yml` for local dev (at minimum: postgres)
+- [ ] ESLint + Prettier configured in `frontend/`
+- [ ] TypeScript strict mode on
+- [ ] Environment variable validation at startup (fail fast)
+- [ ] `.gitignore` covers both `frontend/node_modules` and `backend/__pycache__`, `.venv`, etc.
+
+### Pattern A additions
+
+- [ ] Drizzle configured with Postgres in `frontend/src/lib/db/`
+- [ ] Migration workflow established (`drizzle-kit push` for dev, `migrate` for prod)
+- [ ] Database URL in `frontend/.env`, never hardcoded
+
+### Pattern B additions
+
+- [ ] Backend uses src layout: `backend/src/myapp/`
+- [ ] `pyproject.toml` configured with dependencies and tool settings
+- [ ] OpenAPI spec location agreed and documented in `CLAUDE.md`
+- [ ] `generate:api` script in `frontend/package.json`
+- [ ] Backend `AppConfig.from_env()` validated at startup
+- [ ] Separate `.env` files: `frontend/.env` and `backend/.env`
+- [ ] Alembic configured and `alembic/env.py` imports all ORM models
+
+---
+
+## CLAUDE.md
+
+Every project gets a `CLAUDE.md` at the root. It is the first thing Claude reads at the start
+of any session. Populate it during project setup and keep it current.
+
+```markdown
+# Project: [Name]
+
+## Architecture
+
+Monorepo — [Pattern A (TypeScript Monolith) / Pattern B (BFF)]
+
+## Stack
+
+- Frontend: SvelteKit [version], pnpm
+- Backend: [Python FastAPI / N/A]
+- Database: [Postgres via Drizzle / SQLAlchemy + Alembic]
+- Auth: [describe approach]
+
+## Monorepo layout
+
+- `frontend/` — SvelteKit app (pnpm)
+- `backend/` — Python FastAPI app, src layout (`backend/src/myapp/`)
+- `docker-compose.yml` — local dev stack
+
+## Key conventions
+
+- [Any project-specific deviations from the standard skills]
+- [Anything Claude should know that isn't covered by the skills]
+
+## Skills active on this project
+
+- designing-svelte-ui — UI and design system
+- building-sveltekit-frontend — Frontend architecture
+- building-python-backend — Backend architecture (Pattern B only)
+
+@AGENTS.md
+```
+
+The `@AGENTS.md` reference pulls in the design system decisions from the UI skill.
+`CLAUDE.md` covers architecture; `AGENTS.md` covers visual identity.
+If these do not exist, help the user create them by hand or via the relevant skills.
+
+---
+
+## Cross-cutting Concerns
+
+These span both layers and neither skill covers them fully:
+
+### Auth
+
+- **Pattern A:** Session token in `hooks.server.ts`, `locals.user` set there, guards in loaders
+- **Pattern B:** Frontend hooks set `locals.user` from session. Backend validates its own JWT/token
+  on every request independently — never trust the frontend to enforce auth on the backend.
+
+### Error handling across the stack
+
+- Backend raises domain errors (`AppError` subclasses), maps to HTTP at the FastAPI edge
+- Frontend loader catches HTTP errors, maps to SvelteKit `error()` or `fail()`
+- Never let backend error internals leak to the frontend response body in production
+
+### Shared types (Pattern B)
+
+- The OpenAPI spec is the source of truth — not hand-written TS interfaces
+- Run `cd frontend && pnpm generate:api` after every backend schema change
+- Treat the generated `schema.d.ts` like a lockfile — commit it, don't hand-edit it
+
+### Environment config
+
+- `frontend/.env` and `backend/.env` are always separate, even in Pattern A (future-proofing)
+- They should never share secrets
+- Validate all env vars at startup — `AppConfig.from_env()` on backend, startup check on frontend
+
+---
+
+## Validation Loop
+
+Before handing off the project to the user or an executor agent:
+1. Validate the setup by running appropriate package installation (e.g., `pnpm install` or `uv sync`).
+2. Verify structural configuration, such as validating `docker-compose.yml` with `docker compose config`.
+3. If errors occur, autonomously fix them and repeat until the basic scaffolding checks out.

chisel_checker-0.2.0/skills/building-python-backend/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: building-python-backend
+description: Provides architecture and engineering patterns for production async Python backends. Triggered when scaffolding, building, or reviewing Python backend features, FastAPI routes, SQLAlchemy models, or asyncio patterns. Enforces strict layer separation and domain-driven design.
+---
+
+# Python SWE Skill
+
+Opinionated architecture for production async Python backends. Every layer has one job.
+
+## Reference files
+
+Read these when working in the relevant area:
+
+- `references/layers.md` — Full layer guide: services, repositories, controllers, factory, models
+- `references/fastapi.md` — FastAPI route patterns, dependency injection, error mapping
+- `references/sqlalchemy.md` — ORM models, repository pattern, async session handling
+- `references/patterns-examples.md` — Full code examples for all layers
+
+---
+
+## Blueprint
+
+IMPORTANT: ask the user if they want you to start coding or explicitly invoke the `planning-features` skill to write a detailed plan.
+
+## Architecture Overview
+
+```
+HTTP Layer (FastAPI)
+  ├── routes/              # Thin handlers. Validate input, call factory, return response.
+  ├── dependencies.py      # FastAPI Depends: session, config, request-scoped deps
+  └── error_handlers.py   # AppError → HTTP response mapping. Only place HTTP status lives.
+
+Domain Layer (no FastAPI imports)
+  ├── models/              # Dataclasses. Input/output of every service and controller.
+  ├── errors.py            # AppError hierarchy. Domain errors only, no HTTP codes.
+  ├── services/            # Protocol interface + implementation. One concern each. Never import each other.
+  ├── repositories/        # SQLAlchemy ORM types stay here. Deserialise to domain models immediately.
+  ├── controllers/         # Orchestrate services via TaskGroup. No business logic.
+  └── factory.py           # Assemble everything. Singletons at startup, request-scoped with session.
+
+Config
+  └── config.py            # AppConfig dataclass. Reads from env/secrets at startup. Passed everywhere.
+```
+
+---
+
+## Layer Rules (quick reference)
+
+| Layer         | Can do                                       | Cannot do                                       |
+| ------------- | -------------------------------------------- | ----------------------------------------------- |
+| Route handler | Parse request, call factory, return response | Business logic, direct DB access, service calls |
+| Controller    | Orchestrate services with TaskGroup          | Business logic, DB access, HTTP concerns        |
+| Service       | One domain concern, implement Protocol       | Import other services, HTTP concerns, ORM types |
+| Repository    | SQLAlchemy queries, ORM↔model mapping        | Business logic, calling services                |
+| Factory       | Assemble singletons + request-scoped objects | Logic of any kind                               |
+| Model         | Pure data, dataclass or Pydantic             | Methods with side effects                       |
+
+---
+
+## Key Conventions
+
+### Dataclasses
+
+`slots=True` always. `frozen=True` for immutable value objects, omit for mutable aggregates:
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)   # value object — immutable
+class UserId:
+    value: str
+
+@dataclass(frozen=True, slots=True)   # output model — immutable
+class Recipe:
+    id: str
+    title: str
+    cuisine: str
+
+@dataclass(slots=True)                # input — may be built incrementally
+class CreateRecipeInput:
+    title: str
+    cuisine: str | None = None
+```
+
+### Protocols for interfaces
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class IRecipeService(Protocol):
+    async def get_by_user_id(self, user_id: str) -> list[Recipe]: ...
+    async def create(self, input: CreateRecipeInput) -> Recipe: ...
+```
+
+No ABC, no inheritance. Implementations just match the signature.
+
+### Logging
+
+Bound logger per module, always:
+
+```python
+import structlog
+
+logger: structlog.stdlib.BoundLogger = structlog.getLogger(__name__)
+
+# Bind context for a request/operation
+log = logger.bind(user_id=user_id, recipe_id=recipe_id)
+await log.ainfo("Creating recipe")
+```
+
+### Async — TaskGroup always over gather
+
+```python
+import asyncio
+
+async def get_dashboard(user_id: str) -> Dashboard:
+    async with asyncio.TaskGroup() as tg:
+        recipes_task = tg.create_task(self._recipe_service.get_by_user_id(user_id))
+        pantry_task  = tg.create_task(self._pantry_service.get_by_user_id(user_id))
+
+    return Dashboard(recipes=recipes_task.result(), pantry=pantry_task.result())
+```
+
+Never use `asyncio.gather`. `TaskGroup` propagates exceptions cleanly and cancels siblings on failure.
+
+---
+
+## Code Examples
+
+For full code examples of the architecture layers in practice, please read:
+- **`references/patterns-examples.md`** — Examples for Models, Services, Controllers, Factory, AppConfig, and Error hierarchy.
+
+---
+
+## For detailed patterns, read:
+
+- **Repositories, ORM models, session handling** → `references/sqlalchemy.md`
+- **FastAPI routes, dependency injection, error mapping** → `references/fastapi.md`
+- **Full layer guide with anti-patterns** → `references/layers.md`
+
+## Validation Checklist
+
+Before concluding any implementation task, copy this checklist into your response scratchpad to track your progress:
+- [ ] Run the type-checker (e.g., `pyright .` or `mypy .`) and linter (`ruff check .`).
+- [ ] Run tests (`pytest`).
+- [ ] If errors occur, autonomously fix them and repeat the loop until the checks pass. Do not ask the human to fix your structural or typing errors.