llmframe 0.1.0__tar.gz

llmframe-0.1.0/.agents/skills/add-hexagonal-feature/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: add-hexagonal-feature
+description: Implement a new feature or use case in a Python hexagonal project, including domain modeling, ports, application service, and tests.
+---
+
+# Skill: Add a Hexagonal Feature
+
+Use this skill to implement a new feature, use case, or business capability in
+a Python hexagonal project.
+
+This skill focuses on the application and domain changes needed to add a use
+case cleanly. It owns feature-level orchestration across domain,
+application, and tests. When the change requires a new port or adapter, use
+the specialized skill for that procedure instead of duplicating it here.
+
+## Prerequisites
+
+- The project already has the standard hexagonal `src/` layout.
+- The feature is clear enough that you understand its inputs, outputs, and core
+  business rules.
+
+## Steps
+
+### 1. Name the use case
+
+Choose a clear verb-noun name for the use case, for example `PlaceOrder`,
+`RegisterUser`, or `SendNotification`. Use that name consistently for the
+related files and classes.
+
+### 2. Model the domain if needed
+
+Create or update files under `src/<app_name>/domain/`:
+
+- **Entity** — an object with identity that changes over time.
+- **Value object** — an immutable descriptor (e.g. `EmailAddress`, `Money`).
+- **Domain event** — something that happened (e.g. `OrderPlaced`).
+
+Rules:
+
+- Domain objects must be pure Python with no framework imports or I/O.
+- Use `@dataclass(frozen=True)` for value objects.
+- Raise domain-specific exceptions, not HTTP or database errors.
+
+```python
+# src/<app_name>/domain/<entity>.py
+from dataclasses import dataclass
+
+@dataclass
+class <Entity>:
+    id: str
+```
+
+### 3. Define or confirm the required ports
+
+Identify the application boundaries the feature needs:
+
+- an input port when an external caller invokes a new use case
+- one or more output ports when the application needs infrastructure
+  dependencies such as repositories, publishers, or gateways
+
+If a required port does not exist yet, use `python-add-port` for the detailed
+procedure. In this skill, keep the focus on deciding which boundaries the
+feature needs and making sure the application service depends only on those
+port contracts.
+
+### 4. Implement the application service
+
+Create the use case implementation under `src/<app_name>/application/`:
+
+```python
+class <UseCaseName>:
+    def __init__(self, repository: <EntityRepositoryPort>) -> None:
+        self._repository = repository
+
+    def execute(self, command: <Command>) -> <Result>:
+        ...
+```
+
+Rules:
+
+- The application service depends only on domain objects and port interfaces.
+- It must not import from `adapters/`.
+- It must not perform I/O directly, including `open()`, HTTP calls, or database
+  access.
+- If the feature needs a new adapter implementation for an existing or new
+  port, use `python-add-adapter` for that procedure.
+
+### 5. Write unit tests
+
+Create tests under `tests/unit/`:
+
+```python
+from unittest.mock import MagicMock
+
+def test_<use_case_name>_happy_path() -> None:
+    repo = MagicMock()
+    use_case = <UseCaseName>(repository=repo)
+    use_case.execute(<Command>(...))
+    repo.save.assert_called_once()
+```
+
+TDD is encouraged when it fits the change. Writing tests before the
+implementation is fine and often preferable.
+
+- Use `MagicMock` or a hand-written fake for outbound ports, never real
+  infrastructure.
+- Cover the happy path and at least one failure or edge case.
+
+## Dependency direction reminder
+
+The canonical dependency rules are in `03-architecture-guardrails.md`. This diagram is a quick reference only.
+
+```
+adapters/input   →  application  →  domain
+adapters/output  →  (implements application/ports)
+```
+
+Never let an arrow point in the opposite direction.

llmframe-0.1.0/.agents/skills/bootstrap-python-app/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: bootstrap-python-app
+description: Initialize a new Python project with a hexagonal architecture layout, core tooling, and quality checks.
+---
+
+# Bootstrap a Python Hexagonal Application
+
+Use this skill to initialize a new Python project with a hexagonal
+(ports-and-adapters) architecture.
+
+## Prerequisites
+
+- `uv` is installed (`brew install uv` / `pip install uv`).
+- `<app_name>` — the project and package name.
+- `<python_version>` — for example `3.13`.
+
+## Steps
+
+### 1. Initialize the project with uv
+
+```bash
+uv init <app_name> --python <python_version>
+cd <app_name>
+```
+
+Run the remaining steps from the project root.
+
+### 2. Create the hexagonal `src/` layout
+
+```
+src/
+└── <app_name>/
+    ├── __init__.py
+    ├── domain/          # Pure domain: entities, value objects, domain events
+    │   └── __init__.py
+    ├── application/     # Use cases, application services, port interfaces
+    │   ├── __init__.py
+    │   └── ports/
+    │       └── __init__.py
+    └── adapters/        # Input & output adapter implementations
+        ├── __init__.py
+        ├── input/
+        │   └── __init__.py
+        └── output/
+            └── __init__.py
+tests/
+├── __init__.py
+├── unit/
+│   └── __init__.py
+└── integration/
+    └── __init__.py
+```
+
+Create every directory and `__init__.py` file listed above.
+
+### 3. Configure pyproject.toml
+
+Update the `pyproject.toml` generated by `uv init` to follow this structure.
+Keep the values `uv init` already set for `name`, `version`, and
+`requires-python` unless the user asked for something else.
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "<app_name>"
+version = "0.1.0"
+requires-python = ">= <python_version>"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=6",
+    "mypy>=1.10",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/<app_name>"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py<python_version_nodot>" # e.g. py313 (version without the dot)
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # trailing comma — conflicts with ruff formatter
+    "ISC001",  # implicit string concat — conflicts with ruff formatter
+    "D1",      # missing docstrings — too noisy for early development
+    "ANN",     # type annotations — redundant with mypy strict
+    "TD",      # TODO comment format
+    "FIX",     # fixme comments
+]
+
+[tool.mypy]
+python_version = "<python_version>"
+strict = true
+files = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=src --cov-report=term-missing"
+```
+
+### 4. Install dev dependencies
+
+```bash
+uv sync --all-extras
+```
+
+### 5. Set up pre-commit (optional but recommended)
+
+```bash
+uv add --dev pre-commit
+uv run pre-commit install
+```
+
+Add a minimal `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: <pinned_version>
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+```
+
+Replace `<pinned_version>` with an appropriate pinned release.
+
+### 6. Verify the setup
+
+```bash
+uv run ruff check .
+uv run mypy .
+uv run pytest
+```
+
+All three commands must exit with code 0.
+
+### 7. Write a minimal README
+
+Write a `README.md` that includes:
+
+- What the application does.
+- How to install dependencies (`uv sync --all-extras`).
+- How to run quality checks (`ruff`, `mypy`, `pytest`).
+- A high-level architecture overview (domain / application / adapters).
+
+## Hexagonal architecture conventions
+
+| Layer             | Directory                         | Rule                                                                                 |
+| ----------------- | --------------------------------- | ------------------------------------------------------------------------------------ |
+| Domain            | `src/<app_name>/domain/`          | No imports from `application` or `adapters`. Pure Python only.                       |
+| Application       | `src/<app_name>/application/`     | Depends only on `domain`. Defines port interfaces as ABCs or Protocols.              |
+| Adapters (input)  | `src/<app_name>/adapters/input/`  | Calls into `application`. Uses domain types only through application ports and DTOs. |
+| Adapters (output) | `src/<app_name>/adapters/output/` | Implements port interfaces from `application`.                                       |
+
+If appropriate for the project, enforce these rules with an import linter such
+as `import-linter`, or document them in a root-level `ARCHITECTURE.md`.

llmframe-0.1.0/.agents/skills/format-python-code/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: format-python-code
+description: Formats Python code using ruff and applies safe auto-fixes.
+---
+
+# Skill: Format Python Code
+
+Use this skill to format Python code and apply safe auto-fixes using `ruff`.
+
+## Prerequisites
+
+- `uv` is installed and configured for the project.
+- `ruff` is installed as a development dependency and configured in `pyproject.toml`.
+
+## Steps
+
+### 1. Apply auto-fixes and format
+
+```bash
+uv run ruff check . --fix
+uv run ruff format .
+```
+
+These commands will automatically reformat Python code and apply any safe linting auto-fixes.
+
+## When formatting fails
+
+- If `ruff format .` produces unexpected changes, verify that the project's `pyproject.toml` ruff configuration is correct before overriding the formatter.
+- Unfixable lint violations reported by `ruff check . --fix` will be caught and addressed during the `lint-python-code` step.

llmframe-0.1.0/.agents/skills/lint-python-code/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: lint-python-code
+description: Lints Python code using ruff and mypy for type checking.
+---
+
+# Skill: Lint Python Code
+
+Use this skill to lint Python code using `ruff` and perform type checking with `mypy`.
+
+## Prerequisites
+
+- `uv` is installed and configured for the project.
+- `ruff` and `mypy` are installed as development dependencies and configured in `pyproject.toml`.
+
+## Steps
+
+### 1. Run ruff linting
+
+```bash
+uv run ruff check .
+```
+
+This command checks for linting errors without applying auto-fixes.
+
+### 2. Run mypy type checking
+
+```bash
+uv run mypy .
+```
+
+This command performs static type checking on the Python codebase.
+
+## When linting or type checking fails
+
+- Read the `ruff check` output carefully. Each violation includes a rule code, file path, and line number. Fix the underlying code rather than adding `# noqa` comments unless the suppression is explicitly justified.
+- Do not disable lint rules to silence violations. Prefer refactoring the code to satisfy the rule.
+- Read `mypy` errors and fix the type annotations or logic that caused them. Use `# type: ignore[<code>]` only at narrowly scoped boundaries to genuinely untyped third-party code, and document the reason.
+- If a `mypy` error reflects a genuine design issue (wrong return type, missing protocol method), fix the design rather than suppressing the error.
+- After fixes, re-run both commands to confirm the codebase is clean before proceeding.

llmframe-0.1.0/.agents/skills/python-add-adapter/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: python-add-adapter
+description: Add an input or output adapter to a Python hexagonal project while keeping business logic in the application layer.
+---
+
+# Add an Adapter
+
+Add an input or output adapter to a Python hexagonal project while keeping business logic in the application layer.
+
+This skill owns adapter implementation. If the required application boundary
+does not exist yet, define the port first with `python-add-port`.
+
+## Prerequisites
+
+- The relevant port interface exists in `src/<app_name>/application/ports/`.
+- The adapter technology has been chosen and any required library is installed (for example with `uv add <library>`).
+
+If the port does not exist yet, use `python-add-port` before implementing the
+adapter.
+
+## Input adapter
+
+An input adapter receives external input and calls the application through an input port or service entry point.
+
+### 1. Create the module
+
+```
+src/<app_name>/adapters/input/<adapter_name>/
+    __init__.py
+    adapter.py
+```
+
+Keep `__init__.py` lightweight. Re-export the public symbol only when you want a stable package-level API, and declare `__all__` when it adds clarity:
+
+```python
+from .adapter import router
+
+__all__ = ["router"]
+```
+
+### 2. Implement
+
+- Accept external input and map it to an application command or query DTO.
+- Call the application through its input port or service entry point.
+- Map the result or exception back to the external format.
+- Map domain exceptions to adapter-level error responses.
+- Do not import from `domain/` directly.
+- Keep all business logic in the application service.
+
+### 3. Test
+
+Place tests under `tests/integration/<adapter_name>/`. Test through the framework test client or transport boundary, injecting a fake or stubbed application service to keep tests focused on adapter behavior.
+
+Add unit tests only if the adapter contains meaningful mapping or serialization helpers that warrant direct, framework-free verification.
+
+## Output adapter
+
+An output adapter implements a port interface and talks to external infrastructure.
+
+### 1. Create the module
+
+```
+src/<app_name>/adapters/output/<adapter_name>/
+    __init__.py
+    adapter.py
+```
+
+Keep `__init__.py` lightweight. Re-export the public symbol only when you want a stable package-level API, and declare `__all__` when it adds clarity:
+
+```python
+from .adapter import <AdapterName>
+
+__all__ = ["<AdapterName>"]
+```
+
+### 2. Implement
+
+- Implement all port interface methods.
+- Map infrastructure types to domain objects inside the adapter. Do not expose infrastructure types beyond the adapter boundary.
+- Raise domain exceptions, not infrastructure exceptions.
+- Keep framework clients, ORM models, serializers, and transport-specific configuration inside the adapter package.
+
+### 3. Test
+
+Write unit tests using fakes, stubs, or mocks around the infrastructure boundary. Follow with integration tests against the real infrastructure when adapter behavior depends on actual driver, network, or persistence integration.

llmframe-0.1.0/.agents/skills/python-add-port/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: python-add-port
+description: Add a technology-agnostic application port interface to a Python hexagonal project for a new use case or dependency.
+---
+
+# Add a Port
+
+Use this skill to add a port interface to a Python hexagonal project.
+
+A port defines an application-layer boundary. It describes either how the
+outside world uses the application or what the application needs from external
+systems. A port is not an adapter and must remain technology-agnostic.
+
+This skill owns the detailed procedure for defining new application ports.
+Keep feature orchestration and adapter implementation in related skills.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- expose a new use case through an input port
+- define a new dependency the application needs through an output port
+- extract an application-facing interface so adapters depend on an application
+  contract rather than concrete implementation details
+
+## Prerequisites
+
+- The project follows a hexagonal structure under `src/<app_name>/`.
+- You understand the use case or dependency the port represents.
+- Any command, query, or result DTOs used by the port already exist or are part
+  of the same change.
+
+## Port types
+
+### Input port
+
+An input port defines how the outside world invokes an application use case.
+It is called by an input adapter and implemented by an application service.
+
+Examples:
+
+- `CreateOrderPort`
+- `RegisterUserPort`
+- `GenerateReportPort`
+
+### Output port
+
+An output port defines a dependency the application needs from external
+infrastructure. It is declared by the application and implemented by an output
+adapter.
+
+Examples:
+
+- `OrderRepositoryPort`
+- `EmailSenderPort`
+- `PaymentGatewayPort`
+
+## Steps
+
+### 1. Choose the file and name
+
+Create the interface under:
+
+```
+src/<app_name>/application/ports/
+```
+
+Use a focused file name that matches the responsibility, for example:
+
+- `<use_case_name>_port.py`
+- `<dependency_name>_port.py`
+
+Name both the file and the class by business capability or dependency, not by
+technology.
+
+Good: `CreateInvoicePort`, `CustomerRepositoryPort`
+
+Avoid: `FastAPIPort`, `PostgresPort`, `S3AdapterPort`
+
+### 2. Define the interface
+
+Use `Protocol` by default for lightweight structural typing. Use `ABC` only
+when you need shared abstract behavior or stricter inheritance semantics.
+
+Example:
+
+```python
+from typing import Protocol
+
+from <app_name>.application.commands.create_invoice import CreateInvoiceCommand
+from <app_name>.application.results.create_invoice import CreateInvoiceResult
+
+
+class CreateInvoicePort(Protocol):
+    def execute(self, command: CreateInvoiceCommand) -> CreateInvoiceResult:
+        ...
+```
+
+For output ports, follow the same pattern using domain objects or application
+DTOs in the signature.
+
+### 3. Keep the port clean
+
+- Keep ports in the application layer.
+- Do not import from `adapters/` or infrastructure libraries.
+- Do not embed framework request or response types in port method signatures.
+- Prefer domain objects and application DTOs in method signatures.
+- Keep each port narrowly focused on one use case or one dependency role.
+- Name methods by business intent, not transport or storage mechanics.
+
+For input ports, a single `execute(...)` method is often enough.
+
+For output ports, define only the operations the application needs. Do not
+mirror a full ORM, SDK, or driver API.
+
+### 4. Wire dependencies in the right direction
+
+The arrows below show call/invocation flow (who calls whom), not import dependency direction. For dependency direction rules, see `03-architecture-guardrails.md`.
+
+```text
+input adapters -> input ports -> application service
+application service -> output ports -> output adapters
+```
+
+In practice:
+
+- input adapters depend on input port contracts
+- application services implement input ports
+- application services depend on output port contracts
+- output adapters implement output ports
+
+Never let a port import an adapter or mention a specific framework.
+
+### 5. Test appropriately
+
+Ports are interfaces, so they usually need little or no direct testing.
+
+Test surrounding behavior instead:
+
+- unit test that the application service honors the input port contract
+- unit test that application services call output ports as expected
+- test adapter implementations separately in adapter-focused tests
+
+If the project uses runtime-checkable protocols or shared contract fixtures, add
+small targeted tests only when they provide clear value.
+
+### 6. Review related changes
+
+When adding a new port, check whether the same change needs:
+
+- a new application service implementing the input port
+- a new output adapter implementing the output port
+- new command, query, or result DTOs
+- dependency injection or composition-root wiring updates
+
+If a required adapter does not exist yet, use `python-add-adapter` for that
+follow-up work instead of embedding adapter logic into the port.
+
+If the overall change is a complete end-to-end use case spanning domain,
+application service, and tests, use `add-hexagonal-feature` as the primary
+feature workflow and use this skill only for the port-definition part.

llmframe-0.1.0/.agents/skills/run-local-quality-gate/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: run-local-quality-gate
+description: Orchestrates the execution of Python code formatting, linting, type checking, and testing.
+---
+
+# Skill: Run Local Quality Gate
+
+Use this skill to run the full local quality gate for a Python project, including formatting, linting, type checking, and automated tests.
+
+## Prerequisites
+
+- `uv` is installed and configured for the project.
+- `ruff`, `mypy`, and `pytest` are installed as development dependencies and configured in `pyproject.toml`.
+- The `format-python-code`, `lint-python-code`, and `run-python-tests` skills are available.
+
+## Steps
+
+### 1. Auto-fix and format code
+
+Use the `format-python-code` skill to apply auto-fixes and format the codebase.
+
+### 2. Lint and type check code
+
+Use the `lint-python-code` skill to perform linting and type checking.
+
+### 3. Run automated tests
+
+Use the `run-python-tests` skill to execute all automated tests.
+
+## When a step fails
+
+- If any step fails, stop and fix the underlying issue before proceeding to the next step.
+- Do not bypass `pyproject.toml`-backed tool configuration with ad hoc flags in the final validation run.
+- Run the full quality gate before handoff, even if only a single file changed.
+- Pre-commit hooks provide helpful fast feedback, but they do not replace the full local quality gate.

llmframe-0.1.0/.agents/skills/run-python-tests/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: run-python-tests
+description: Runs automated tests for a Python project using pytest.
+---
+
+# Skill: Run Python Tests
+
+Use this skill to run automated tests for a Python project using `pytest`.
+
+## Prerequisites
+
+- `uv` is installed and configured for the project.
+- `pytest` is installed as a development dependency and configured in `pyproject.toml`.
+
+## Steps
+
+### 1. Run all tests
+
+```bash
+uv run pytest
+```
+
+This command executes all tests defined in the project.
+
+### 2. Run focused tests (optional)
+
+```bash
+uv run pytest tests/<path_to_test_file>
+uv run pytest -k "<pattern>"
+```
+
+Use these commands to run a subset of tests during development.
+
+## When tests fail
+
+- Read the test output to identify the failing test and the assertion or exception that caused the failure.
+- Fix the root cause in the source code or test rather than skipping or deleting the test.
+- Use `uv run pytest -x` to stop at the first failure during iterative debugging.
+- For flaky or slow tests, document the reason and mitigation in the handoff notes rather than silently ignoring them.
+- After fixes, re-run the full test suite with `uv run pytest` before handoff.