strands-compose 0.1.0__tar.gz

strands_compose-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,124 @@
+name: Bug Report
+description: Report a bug in strands-compose
+title: "[BUG] "
+labels: ["bug", "triage"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report for strands-compose!
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: I have updated to the latest version of strands-compose
+          required: true
+        - label: I have checked the documentation and this is not expected behavior
+          required: true
+        - label: I have searched [./issues](./issues?q=) and there are no duplicates of my issue
+          required: true
+
+  - type: input
+    id: compose-version
+    attributes:
+      label: strands-compose Version
+      description: Which version of strands-compose are you using?
+      placeholder: e.g., 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: strands-version
+    attributes:
+      label: strands-agents Version
+      description: Which version of strands-agents are you using?
+      placeholder: e.g., 1.32.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Which version of Python are you using?
+      placeholder: e.g., 3.11.5
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: Which operating system are you using?
+      placeholder: e.g., Ubuntu 22.04 / Windows 11 / macOS 14
+    validations:
+      required: true
+
+  - type: dropdown
+    id: installation-method
+    attributes:
+      label: Installation Method
+      description: How did you install strands-compose?
+      options:
+        - pip
+        - uv
+        - git clone
+        - other
+    validations:
+      required: true
+
+  - type: textarea
+    id: config-yaml
+    attributes:
+      label: Relevant YAML Config
+      description: Paste the relevant portion of your `config.yaml` (remove any secrets)
+      render: yaml
+
+  - type: textarea
+    id: steps-to-reproduce
+    attributes:
+      label: Steps to Reproduce
+      description: Detailed steps to reproduce the behavior
+      placeholder: |
+        1. config.yaml and code snippet (minimal reproducible example)
+        2. Run the command...
+        3. See error...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: A clear description of what you expected to happen
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happened — include full traceback if applicable
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other relevant information, logs, screenshots, etc.
+
+  - type: textarea
+    id: possible-solution
+    attributes:
+      label: Possible Solution
+      description: Optional — if you have suggestions on how to fix the bug
+
+  - type: input
+    id: related-issues
+    attributes:
+      label: Related Issues
+      description: Optional — link to related issues if applicable

strands_compose-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: strands-compose Discussions
+    url: https://github.com/strands-compose/sdk-python/discussions
+    about: Please ask and answer questions here
+  - name: strands-compose Documentation
+    url: https://github.com/strands-compose/sdk-python/tree/main/docs
+    about: Visit the documentation for help

strands_compose-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature Request
+description: Suggest a new feature or enhancement for strands-compose
+title: "[FEATURE] "
+labels: ["enhancement", "triage"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting a new feature for strands-compose!
+
+  - type: textarea
+    id: problem-statement
+    attributes:
+      label: Problem Statement
+      description: Describe the problem you're trying to solve. What is currently difficult or impossible to do?
+      placeholder: I would like strands-compose to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: Optional — describe your proposed solution. How would this feature work? Include example YAML or Python if helpful.
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: Provide specific use cases for the feature. How would people use it?
+      placeholder: This would help with...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Optional — have you considered alternative approaches? What are their pros and cons?
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any other context, screenshots, code examples, or references that might help understand the request.

strands_compose-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,42 @@
+## Description
+
+<!-- Provide a detailed description of the changes in this PR -->
+
+## Related Issues
+
+<!-- Link to related issues using #issue-number format -->
+
+## Type of Change
+
+<!-- Choose one and delete the rest -->
+
+- Bug fix
+- New feature
+- Breaking change
+- Documentation update
+- Other (please describe):
+
+## YAML / API Impact
+
+<!-- Does this change affect the config schema or the public Python API?
+     If yes, describe what changes and whether it's backwards-compatible. -->
+
+## Testing
+
+How have you tested the change?
+
+- [ ] I ran `uv run just check` (lint + type check)
+- [ ] I ran `uv run just test` for overall testing
+- [ ] I added or updated tests that prove my fix is effective or my feature works
+- [ ] I verified existing examples in `examples/` still work
+
+## Checklist
+
+- [ ] I have read the [CONTRIBUTING](CONTRIBUTING.md) document
+- [ ] I have updated the documentation accordingly
+- [ ] My changes generate no new warnings
+- [ ] Any dependent changes have been merged and published
+
+---
+
+By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

strands_compose-0.1.0/.github/agents/developer.md

@@ -0,0 +1,38 @@
+---
+name: developer
+description: Implements features and fixes bugs in strands-compose following all project architecture and coding conventions
+---
+
+You are an expert contributor to strands-compose. Your job is to implement features and fix bugs while strictly following the project's architecture.
+
+## Workflow
+
+1. Read the issue carefully. Identify the minimal change needed.
+2. Check `.venv/lib/python*/site-packages/strands/` — if strands already provides what is needed, use it directly.
+3. Identify which module(s) should change using the Directory Structure in the repo instructions.
+4. Implement the change with full type annotations, Google-style docstrings, and structured logging.
+5. Write or update unit tests in `tests/unit/` mirroring the changed module path.
+6. Run `uv run just check` — fix all lint, type, and security issues before proceeding.
+7. Run `uv run just test` — all tests must pass.
+8. Open a draft PR with a clear description of what changed and why.
+
+## Where New Code Goes
+
+- New YAML config key → `src/strands_compose/models.py` (Pydantic model) + `src/strands_compose/config/schema.py` (JSON schema)
+- New resolver → `src/strands_compose/config/resolvers/`
+- New built-in hook → `src/strands_compose/hooks/`
+- New MCP transport or lifecycle change → `src/strands_compose/mcp/`
+- New converter → `src/strands_compose/converters/`
+- New tool helper → `src/strands_compose/tools/`
+- New renderer → `src/strands_compose/renderers/`
+- Public API changes → `src/strands_compose/__init__.py`
+
+## Hard Rules
+
+- Never modify files outside the scope of the issue.
+- Never reimplement what strands already provides.
+- Every new public function, method, and class needs a docstring and full type hints.
+- No `Optional`, `Union`, `List`, `Dict` — use `X | None`, `list`, `dict`.
+- No f-strings in `logger.*` calls — use `%s` with field-value pairs.
+- Raise specific exceptions with context; never swallow with bare `except:`.
+- `from __future__ import annotations` at the top of every module you create or edit.

strands_compose-0.1.0/.github/agents/docs-writer.md

@@ -0,0 +1,48 @@
+---
+name: docs-writer
+description: Writes and updates documentation for strands-compose — README, examples, and configuration reference chapters
+---
+
+You are a documentation specialist for strands-compose. Your job is to write and improve documentation so that users can understand and use the library effectively.
+
+## Workflow
+
+1. Identify what needs documenting from the issue or PR.
+2. Determine the correct location for the change (see below).
+3. Write clear, concise, accurate documentation. Test any YAML or Python examples by running them.
+4. Run `uv run just check` to ensure no markdown lint issues.
+5. Open a PR scoped only to documentation changes.
+
+## Where Documentation Lives
+
+| Content | Location |
+|---------|----------|
+| Project overview, installation, quick-start | `README.md` |
+| YAML configuration reference (per-feature) | `docs/configuration/Chapter_XX.md` |
+| Quick recipes / how-tos | `docs/configuration/Quick_Recipes.md` |
+| Example projects | `examples/NN_name/` — each needs `config.yaml`, `main.py`, `README.md` |
+| Release history | `CHANGELOG.md` — follows Keep a Changelog format |
+
+## Writing Rules
+
+- Use plain English. Short sentences. Active voice.
+- Every documented feature needs a minimal working YAML example.
+- YAML examples must use valid strands-compose syntax — verify against the JSON schema in `src/strands_compose/config/schema.py`.
+- Python examples must be runnable as-is.
+- Do not document internal implementation details — only the public API and YAML config surface.
+- Use relative links (never absolute URLs) for files within the repository.
+- Keep `README.md` concise — link out to `docs/` for detail rather than expanding inline.
+
+## Examples
+
+When adding a new example under `examples/`:
+- Follow the naming pattern: `NN_short_name/` (next available number)
+- The `README.md` must explain what the example demonstrates and how to run it.
+- Use `TEMPLATE_EXAMPLE.md` in `examples/` as a structural guide.
+- Run `uv run just test` — there is a smoke test suite in `tests/examples/` that runs all examples.
+
+## What Not to Change
+
+- Do not modify source code.
+- Do not edit `docs/configuration/` chapters without understanding the full feature — ask for clarification in the issue if unsure.
+- Do not remove existing examples without an explicit request.

strands_compose-0.1.0/.github/agents/reviewer.md

@@ -0,0 +1,46 @@
+---
+name: reviewer
+description: Reviews code in pull requests for correctness, style, architecture compliance, and security in strands-compose
+---
+
+You are a senior code reviewer for strands-compose. Your job is to review pull requests and leave precise, actionable feedback. You enforce the project rules strictly but fairly.
+
+## Review Workflow
+
+1. Read the PR description and linked issue to understand the intended change.
+2. Check that the change is minimal — flag any refactoring of unrelated code.
+3. Run `uv run just check` — report any lint, type, or security failures.
+4. Run `uv run just test` — report any test failures or coverage regressions.
+5. Leave inline comments on specific lines. Request changes for rule violations; suggest (not require) improvements for style.
+
+## What to Check
+
+### Architecture
+- [ ] Change is placed in the correct module (see Directory Structure in repo instructions)
+- [ ] No strands functionality reimplemented — check `.venv/lib/python*/site-packages/strands/`
+- [ ] No global state, singletons, or auto-registration introduced
+- [ ] Public API changes are reflected in `src/strands_compose/__init__.py`
+
+### Python rules
+- [ ] `from __future__ import annotations` present in every modified module
+- [ ] All functions/methods fully typed (parameters + return type)
+- [ ] No `Optional`, `Union`, `List`, `Dict` — only `X | None`, `list`, `dict`
+- [ ] Google-style docstring on every new public class, function, and method
+- [ ] Class docstrings on `__init__`, not the class body
+- [ ] No f-strings in `logger.*` calls — `%s` field-value pairs only
+- [ ] No bare `except:` — specific exception types with context messages
+- [ ] Properties returning mutable state return copies: `return list(self._items)`
+- [ ] No hardcoded secrets, no `eval()`, `exec()`, `subprocess(shell=True)`
+
+### Tests
+- [ ] New public code has tests in `tests/unit/` mirroring the source path
+- [ ] Error paths are tested with `pytest.raises`
+- [ ] Tests are named descriptively
+
+### Commits
+- [ ] Commit messages follow conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
+- [ ] No "WIP" commits in the final PR
+
+## Tone
+
+Be direct and specific. Quote the problematic line. Explain why it violates a rule and what the fix should be. Don't leave vague comments like "consider refactoring this".

strands_compose-0.1.0/.github/agents/tester.md

@@ -0,0 +1,37 @@
+---
+name: tester
+description: Writes and improves tests for strands-compose — unit, integration, and example smoke tests
+---
+
+You are a testing specialist for strands-compose. Your job is to add missing tests, improve coverage, and ensure all test behaviour is correct and well-structured.
+
+## Workflow
+
+1. Identify what is under-tested: missing unit tests, edge cases, or error paths.
+2. Place new test files in `tests/unit/` mirroring the `src/strands_compose/` path (e.g. `src/strands_compose/hooks/stop_guard.py` → `tests/unit/hooks/test_stop_guard.py`).
+3. Write tests using `pytest` — use `fixtures`, `parametrize`, and `tmp_path`. Mock all external dependencies.
+4. Run `uv run just test` — all tests must pass and coverage must remain ≥ 70%.
+5. Run `uv run just check` — tests must also pass lint and type checks.
+
+## Test Structure Rules
+
+- Test **behaviour**, not implementation details.
+- Name tests descriptively: `test_<what>_<condition>_<expected_outcome>`.
+  - Good: `test_interpolate_missing_var_without_default_raises_value_error`
+  - Bad: `test_interpolate_1`
+- One `assert` concept per test where practical — split into multiple tests rather than one large test.
+- Use `pytest.raises` with `match=` to assert exception messages.
+- Mock at the boundary: patch I/O, network, and strands internals — not internal logic you're testing.
+- Use `tmp_path` for any file system interactions.
+
+## Coverage Targets
+
+- Every public function and method must have at least one test.
+- Error paths (`ValueError`, `KeyError`, `RuntimeError`, etc.) each need a dedicated test.
+- Parametrize repetitive cases instead of copy-pasting test bodies.
+
+## What Not to Change
+
+- Do not modify source code to make tests pass — fix the test or raise an issue.
+- Do not add integration tests for behaviour already covered by unit tests.
+- Do not remove existing tests unless they are genuinely wrong or duplicate.

strands_compose-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,176 @@
+# strands-compose — Copilot Instructions
+
+This is **strands-compose**: a declarative multi-agent orchestration library for [strands-agents](https://github.com/strands-agents/sdk-python).
+It reads YAML configs and returns fully wired, plain `strands` objects — no wrappers, no subclasses.
+
+---
+
+## Architecture — NON-NEGOTIABLE
+
+1. **Strands-first** — always check `.venv/lib/python*/site-packages/strands/` before implementing anything. If strands provides it, use it directly.
+2. **Thin wrapper** — translate YAML → Python objects, then get out of the way.
+3. **Composition over inheritance** — small, focused components that compose.
+4. **Explicit over implicit** — no auto-registration, no global singletons.
+5. **Single responsibility** — each module does one thing.
+6. **Testable in isolation** — no global state, every unit testable without other components.
+
+## Python Rules
+
+- `from __future__ import annotations` at the top of every module.
+- Every public function/method/class must be fully typed — parameters and return type.
+- Use `X | None`, `X | Y`, `list`, `dict`, `tuple` — never `Optional`, `Union`, `List`, `Dict`.
+- Google-style docstrings on every public class, function, and method.
+- Class docstring goes on `__init__`, not the class body.
+- Early returns always — handle edge cases first, max 3 nesting levels.
+- Raise specific exceptions (`ValueError`, `KeyError`, `TypeError`, `RuntimeError`) with context.
+- Never silently swallow exceptions. No bare `except:`.
+- Return copies from properties: `return list(self._items)`.
+- `logging.getLogger(__name__)` — never `print()` for diagnostics.
+- No `eval()`, `exec()`, `pickle` for untrusted data, `subprocess(shell=True)`.
+- No hardcoded secrets — use env vars.
+- Import order: stdlib → third-party → local (ruff-enforced).
+- `__all__` only in `__init__.py`.
+
+## Naming
+
+- Classes: `PascalCase` | functions/methods: `snake_case` | constants: `UPPER_SNAKE_CASE` | private: `_prefix`
+- No abbreviations in public API. Boolean params: `is_`, `has_`, `enable_` prefixes.
+
+## Key Strands APIs (do NOT reimplement)
+
+| What | Import path |
+|------|-------------|
+| `Agent` | `strands.agent.agent` |
+| Hook events | `strands.hooks.events` — `BeforeInvocationEvent`, `AfterInvocationEvent`, `BeforeModelCallEvent`, `AfterModelCallEvent`, `BeforeToolCallEvent`, `AfterToolCallEvent` |
+| `HookProvider` | `strands.hooks` — implement `register_hooks(registry)` |
+| `MCPClient` | `strands.tools.mcp.mcp_client` |
+| `SessionManager` | `strands.session` — `FileSessionManager`, `S3SessionManager` |
+| Multi-agent | `strands.multiagent` — `Swarm`, `Graph` |
+| `ToolRegistry` | `strands.tools.registry` |
+| `@tool` decorator | `strands.tools.decorator` |
+
+## Testing
+
+- Every public function gets at least one test. Test behavior, not implementation.
+- Use pytest fixtures, `parametrize`, `tmp_path`. Mock external dependencies.
+- Name tests descriptively: `test_interpolate_missing_var_without_default_raises_value_error`.
+
+## Tooling
+
+```bash
+uv run just install      # install deps + git hooks (once after clone)
+uv run just check        # lint + type check + security scan
+uv run just test         # pytest with coverage (≥70%)
+uv run just format       # auto-format with ruff
+```
+
+## Directory Structure
+
+```
+src/strands_compose/
+├── __init__.py              # Public API — load(), ResolvedConfig
+├── models.py                # Pydantic config models (AgentConfig, ModelConfig, …)
+├── types.py                 # Shared type aliases
+├── utils.py                 # Miscellaneous helpers
+├── exceptions.py            # Custom exception hierarchy
+├── wire.py                  # Final assembly — wires all resolved objects into ResolvedConfig
+├── config/                  # YAML loading, validation, interpolation
+│   ├── schema.py            # JSON-schema for config validation
+│   ├── interpolation.py     # ${VAR:-default} interpolation
+│   ├── loaders/             # File/string/dict loaders, helpers, validators
+│   └── resolvers/           # Per-key resolvers (agents, models, mcp, hooks, …)
+│       └── orchestrations/  # Orchestration builder and planner
+│           ├── builders.py  # Build delegate, swarm, graph objects
+│           └── planner.py   # Resolve orchestration config to plan
+├── converters/              # Config dict → strands objects
+│   ├── base.py              # BaseConverter protocol
+│   ├── openai.py            # OpenAI-specific conversion
+│   └── raw.py               # Raw/passthrough conversion
+├── hooks/                   # Built-in HookProvider implementations
+│   ├── event_publisher.py   # Streaming event queue publisher
+│   ├── max_calls_guard.py   # Max tool-call circuit breaker
+│   ├── stop_guard.py        # Agent stop-signal hook
+│   └── tool_name_sanitizer.py  # Sanitize tool names for model compatibility
+├── mcp/                     # MCP server/client lifecycle
+│   ├── client.py            # MCPClient factory and wiring
+│   ├── lifecycle.py         # Server startup, readiness polling, shutdown
+│   ├── server.py            # Local Python server launcher
+│   └── transports.py        # Transport builders (stdio, streamable_http)
+├── renderers/               # Terminal output rendering
+│   ├── base.py              # BaseRenderer protocol
+│   └── ansi.py              # ANSI colour renderer
+├── startup/                 # Post-load validation and reporting
+│   ├── validator.py         # Config correctness checks
+│   └── report.py            # Human-readable startup report
+└── tools/                   # Tool loading helpers
+    ├── extractors.py        # Extract @tool functions from modules
+    ├── loaders.py           # Import modules by path/name
+    └── wrappers.py          # Wrap callables as strands tools
+
+tests/
+├── unit/                    # Unit tests (mirrors src/ structure)
+│   ├── config/              # Tests for config loading, schema, interpolation, resolvers
+│   ├── converters/          # Tests for converter modules
+│   ├── hooks/               # Tests for hook providers
+│   ├── mcp/                 # Tests for MCP lifecycle
+│   ├── models/              # Tests for Pydantic config models
+│   ├── renderers/           # Tests for renderers
+│   └── startup/             # Tests for validator and report
+├── integration/             # Integration tests (real strands objects)
+└── examples/                # Smoke tests for all examples/
+```
+
+## Logging Style
+
+Use `%s` interpolation with structured field-value pairs — never f-strings:
+
+```python
+# Good
+logger.debug("agent_id=<%s>, tool=<%s> | tool call started", agent_id, tool_name)
+logger.warning("path=<%s>, reason=<%s> | config file not found", path, reason)
+
+# Bad
+logger.debug(f"Tool {tool_name} called on agent {agent_id}")  # no f-strings
+logger.info("Config loaded.")                                  # no punctuation
+```
+
+- Field-value pairs first: `key=<value>` separated by commas
+- Human-readable message after ` | `
+- `<>` around values (makes empty values visible)
+- Lowercase messages, no trailing punctuation
+- `%s` format strings, not f-strings (lazy evaluation)
+
+## Things to Do
+
+- Check `.venv/lib/python*/site-packages/strands/` before implementing — use strands if it exists
+- `from __future__ import annotations` at the top of every module
+- Fully type every function signature (parameters + return type)
+- Google-style docstring on every public class, function, and method
+- Put class docstrings on `__init__`, not the class body
+- Early returns — handle edge cases first, max 3 nesting levels
+- Raise specific exceptions (`ValueError`, `KeyError`, `TypeError`, `RuntimeError`) with context
+- Return copies from properties exposing mutable state: `return list(self._items)`
+- Use structured logging with `%s` and field-value pairs
+- Run `uv run just check` then `uv run just test` before committing
+
+## Things NOT to Do
+
+- Don't reimplement what strands already provides — check first
+- Don't use `Optional[X]`, `Union[X, Y]`, `List`, `Dict` — use `X | None`, `list`, `dict`
+- Don't use `print()` for diagnostics — use `logging.getLogger(__name__)`
+- Don't use f-strings in log calls — use `%s` interpolation
+- Don't swallow exceptions silently — no bare `except:`
+- Don't add `__all__` outside `__init__.py`
+- Don't hardcode secrets — use env vars
+- Don't use `eval()`, `exec()`, `pickle` for untrusted data, or `subprocess(shell=True)`
+- Don't commit without running `uv run just check`
+- Don't add comments about what changed or temporal context ("recently refactored", "moved from")
+
+## Agent-Specific Notes
+
+- Make the **smallest reasonable change** to achieve the goal — don't refactor unrelated code
+- Prefer simple, readable, maintainable solutions over clever ones
+- When unsure where something belongs, check the Directory Structure above
+- Comments should explain **what** and **why**, never **when** or **how it changed**
+- If you find something broken while working, fix it — don't leave it commented out
+- Never add or change files outside the scope of the task

strands_compose-0.1.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 100
+    commit-message:
+      prefix: ci
+    groups:
+      dev-dependencies:
+        patterns:
+          - "pytest"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 100
+    commit-message:
+      prefix: ci

strands_compose-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+# Continuous Integration — runs on every push and pull request.
+
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_call:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # ── Quality checks (format · lint · type · security) ──────────────────────
+  check:
+    name: Quality checks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Install dev deps
+        run: uv sync --all-groups --all-extras
+
+      - name: Ruff — format check
+        run: uv run just check-format
+
+      - name: Ruff — lint
+        run: uv run just check-code
+
+      - name: ty — type check
+        run: uv run just check-type
+
+      - name: Bandit — security scan
+        run: uv run just check-security
+
+  # ── Tests ──────────────────────────────────────────────────────────────────
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Install dev deps
+        run: uv sync --all-groups --all-extras
+
+      - name: pytest with coverage
+        run: uv run just test