chore: add copilot agents, skills, and path-specific instructions

.github/agents/developer.md → .github/agents/developer.agent.md

@@ -1,9 +1,27 @@
 ---
 name: developer
 description: Implements features and fixes bugs in strands-compose following all project architecture and coding conventions
+tools: [
+  "read", "edit", "search", "execute", "agent", "web", "todo",
+  "strands-agents/*", "aws-documentation-mcp-server/*",
+]
 ---
 
-You are an expert contributor to strands-compose. Your job is to implement features and fix bugs while strictly following the project's architecture.
+You are an expert contributor to strands-compose. Your job is to implement features and fix bugs while strictly following the project's architecture and coding conventions.
+
+**Read `AGENTS.md` first** — it is the single source of truth for architecture, Python rules, naming, logging style, key APIs, and directory structure. Everything below supplements those rules for the developer workflow.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute Python and project commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run python script.py           # run any Python script
+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
+```
 
 ## Workflow
 

.github/agents/docs-writer.md → .github/agents/docs-writer.agent.md

@@ -1,10 +1,26 @@
 ---
 name: docs-writer
 description: Writes and updates documentation for strands-compose — README, examples, and configuration reference chapters
+tools: [
+  "read", "edit", "search", "execute", "web", "todo",
+  "strands-agents/*", "aws-documentation-mcp-server/*",
+]
 ---
 
 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.
 
+**Read `AGENTS.md` first** — it contains the project architecture, directory structure, key APIs, and coding conventions. Your documentation must be consistent with what is defined there.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute Python and project commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run python examples/01_minimal/main.py   # run an example
+uv run just check                            # lint + type check + security scan
+uv run just format                           # auto-format with ruff
+```
+
 ## Workflow
 
 1. Identify what needs documenting from the issue or PR.

.github/agents/reviewer.md → .github/agents/reviewer.agent.md

@@ -1,10 +1,25 @@
 ---
 name: reviewer
 description: Reviews code in pull requests for correctness, style, architecture compliance, and security in strands-compose
+tools: [
+  "read", "search", "execute", "web", "todo",
+  "strands-agents/*", "aws-documentation-mcp-server/*",
+]
 ---
 
 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.
 
+**Read `AGENTS.md` first** — it is the single source of truth for architecture, Python rules, naming, logging style, key APIs, and directory structure. The checklist below is derived from those rules.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run just check   # lint + type check + security scan
+uv run just test    # pytest with coverage (≥70%)
+```
+
 ## Review Workflow
 
 1. Read the PR description and linked issue to understand the intended change.

.github/agents/tester.md → .github/agents/tester.agent.md

@@ -1,10 +1,24 @@
 ---
 name: tester
 description: Writes and improves tests for strands-compose — unit, integration, and example smoke tests
+tools: ["agent", "read", "edit", "search", "execute", "web", "todo"]
 ---
 
 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.
 
+**Read `AGENTS.md` first** — it defines the project architecture, Python rules, logging conventions, and testing requirements. Everything below supplements those rules for the testing workflow.
+
+## Environment
+
+This project uses **uv** as the package manager and task runner. Always use `uv run` to execute commands — never bare `python`, `pip`, or `pytest`:
+
+```bash
+uv run just test                   # pytest with coverage (≥70%)
+uv run just check                  # lint + type check + security scan
+uv run pytest tests/unit/hooks/test_stop_guard.py   # run a specific test file
+uv run pytest -k "test_name"       # run a specific test by name
+```
+
 ## Workflow
 
 1. Identify what is under-tested: missing unit tests, edge cases, or error paths.

.github/copilot-instructions.md

@@ -174,3 +174,34 @@ logger.info("Config loaded.")                                  # no punctuation
 - 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
+
+## Custom Agents
+
+Specialized agents are defined in `.github/agents/`. Select the right one for your task:
+
+| Agent | Purpose | Tool Access |
+|-------|---------|-------------|
+| `developer` | Implement features and fix bugs | read, edit, search, execute, agent |
+| `reviewer` | Review PRs for correctness and compliance | read, search, execute (read-only) |
+| `tester` | Write and improve tests | read, edit, search, execute, agent |
+| `docs-writer` | Write and update documentation | read, edit, search, execute |
+
+## Skills
+
+Skills in `.github/skills/` are **automatically activated** when relevant:
+
+| Skill | Triggered When |
+|-------|---------------|
+| `check-and-test` | Validating, linting, testing, or checking code quality |
+| `strands-api-lookup` | Working with strands APIs, checking upstream functionality |
+
+## Path-Specific Instructions
+
+Targeted rules in `.github/instructions/` are applied automatically based on file paths:
+
+| File | Applies To |
+|------|-----------|
+| `source.instructions.md` | `src/**/*.py` |
+| `tests.instructions.md` | `tests/**/*.py` |
+| `examples.instructions.md` | `examples/**/*.py`, `examples/**/*.yaml` |
+| `docs.instructions.md` | `docs/**/*.md` |

.github/instructions/docs.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "docs/**/*.md"
+---
+
+# Documentation Instructions
+
+- Use plain English. Short sentences. Active voice.
+- Show `uv run` in all command examples — never bare `python`, `pip`, or `pytest`.
+- 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 with `uv run python`.
+- Do not document internal implementation details — only the public API and YAML config surface.
+- Use relative links for files within the repository (never absolute URLs).
+- Keep content consistent with `AGENTS.md` rules and the Key APIs table.

.github/instructions/examples.instructions.md

@@ -0,0 +1,15 @@
+---
+applyTo: "examples/**/*.py,examples/**/*.yaml"
+---
+
+# Example Code Instructions
+
+Examples must be complete, runnable, and easy to understand.
+
+- Every example directory needs `config.yaml`, `main.py`, and `README.md`.
+- Python files must be runnable as-is with `uv run python examples/NN_name/main.py`.
+- YAML files must use valid strands-compose syntax.
+- Show `uv run` in all command examples — never bare `python` or `pip`.
+- Keep examples minimal — demonstrate one concept per example.
+- Do not import private/internal APIs — only use the public API from `strands_compose`.
+- Use `examples/TEMPLATE_EXAMPLE.md` as a structural guide for new examples.

.github/instructions/source.instructions.md

@@ -0,0 +1,16 @@
+---
+applyTo: "src/**/*.py"
+---
+
+# Source Code Instructions
+
+All Python rules from `AGENTS.md` apply. Key reminders for source files:
+
+- Execute with `uv run python script.py` — never bare `python`.
+- `from __future__ import annotations` at the top of every module.
+- Full type annotations on all public functions (parameters + return type).
+- Use `X | None`, `list`, `dict` — never `Optional`, `Union`, `List`, `Dict`.
+- Google-style docstring on every public class, function, and method. Class docstrings go on `__init__`.
+- Structured logging with `%s` and field-value pairs — never f-strings in `logger.*` calls.
+- Check `.venv/lib/python*/site-packages/strands/` before implementing — do NOT reimplement upstream functionality.
+- Run `uv run just check` and `uv run just test` before committing.

.github/instructions/tests.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "tests/**/*.py"
+---
+
+# Test Code Instructions
+
+All Python rules from `AGENTS.md` apply. Additional rules for test files:
+
+- `from __future__ import annotations` at the top of every test module.
+- Name tests descriptively: `test_<what>_<condition>_<expected_outcome>`.
+- Test **behaviour**, not implementation details.
+- One `assert` concept per test where practical.
+- Use `pytest.raises` with `match=` for exception tests.
+- Mock at the boundary: patch I/O, network, and strands internals — not internal logic.
+- Use `tmp_path` for file system interactions.
+- Parametrize repetitive cases instead of copy-pasting test bodies.
+- Run tests with `uv run just test` — never bare `pytest`.
+- In edge cases use `uv run pytest ...` for faster iteration.
+- Coverage must remain ≥ 70%.

.github/skills/check-and-test/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: check-and-test
+description: Run lint, type checks, security scan, and tests for strands-compose. Use this when asked to validate, check, lint, test, or verify code quality.
+---
+
+# Check and Test
+
+Run the full validation pipeline before committing or opening a PR.
+
+## Steps
+
+1. Run lint, type check, and security scan:
+
+```bash
+uv run just check
+```
+
+2. If `check` fails, auto-format first and re-run:
+
+```bash
+uv run just format
+uv run just check
+```
+
+3. Run the test suite with coverage:
+
+```bash
+uv run just test
+```
+
+4. If a specific test fails, run it in isolation for faster debugging:
+
+```bash
+uv run pytest tests/unit/hooks/test_stop_guard.py -x -v
+uv run pytest -k "test_name" -x -v
+```
+
+## Coverage
+
+Coverage must remain **≥ 70%**. If coverage drops, add tests for the uncovered code before proceeding.
+
+## Troubleshooting
+
+- **Import errors**: Run `uv sync --all-groups --all-extras` to sync dependencies.
+- **Type errors**: Check for missing `from __future__ import annotations` at the top of the module.
+- **Lint errors**: Run `uv run just format` first — it fixes most style issues automatically.

.github/skills/strands-api-lookup/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: strands-api-lookup
+description: Look up strands-agents APIs before implementing. Use this when working with strands Agent, hooks, MCP, sessions, multi-agent orchestration, or tool registry.
+---
+
+# Strands API Lookup
+
+Before implementing anything, check whether strands-agents already provides it. This project is a **thin wrapper** — reimplementing upstream functionality is a rule violation.
+
+## Key APIs — Do NOT Reimplement
+
+| What | Import | Purpose |
+|------|--------|---------|
+| `Agent` | `strands.agent.agent` | Core agent class |
+| Hook events | `strands.hooks.events` | `BeforeInvocationEvent`, `AfterInvocationEvent`, `BeforeModelCallEvent`, `AfterModelCallEvent`, `BeforeToolCallEvent`, `AfterToolCallEvent` |
+| `HookProvider` | `strands.hooks` | Implement `register_hooks(registry)` |
+| `MCPClient` | `strands.tools.mcp.mcp_client` | MCP tool client |
+| `SessionManager` | `strands.session` | `FileSessionManager`, `S3SessionManager` |
+| Multi-agent | `strands.multiagent` | `Swarm`, `Graph` |
+| `ToolRegistry` | `strands.tools.registry` | Tool registration |
+| `@tool` decorator | `strands.tools.decorator` | Decorator-based tool definition |
+
+## strands-compose Public API
+
+Always import from the **top-level** `strands_compose` package — never from submodules:
+
+```python
+# Good — top-level public API
+from strands_compose import load, load_config, resolve_infra, load_session
+from strands_compose import AppConfig, ResolvedConfig, ResolvedInfra
+from strands_compose import EventQueue, StreamEvent
+
+# Bad — reaching into submodules
+from strands_compose.config.loaders import load_config      # DON'T
+from strands_compose.config.resolvers import resolve_infra   # DON'T
+```
+
+## How to Check
+
+1. Search the strands public API:
+
+```bash
+uv run python -c "import strands; print(dir(strands))"
+```
+
+2. Check the strands Agent API:
+
+```bash
+uv run python -c "from strands import Agent; help(Agent)"
+```
+
+3. Search the installed strands package directly:
+
+```bash
+find .venv/lib/python*/site-packages/strands/ -name "*.py" | head -30
+grep -r "def function_name" .venv/lib/python*/site-packages/strands/
+```
+
+4. If the functionality exists upstream, import and use it directly.
+5. If it does not exist, implement it in this project following `AGENTS.md` rules.

.github/workflows/ci.yml

@@ -26,13 +26,10 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           enable-cache: true
 
-      - name: Install just
-        uses: extractions/setup-just@v4
-
       - name: Install dev deps
         run: uv sync --all-groups --all-extras
 
@@ -62,14 +59,11 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 
-      - name: Install just
-        uses: extractions/setup-just@v4
-
       - name: Install dev deps
         run: uv sync --all-groups --all-extras
 

.github/workflows/publish.yml

@@ -40,7 +40,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: astral-sh/setup-uv@v8.0.0
         with:
           enable-cache: true
 
@@ -86,18 +86,15 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: astral-sh/setup-uv@v7
+      - uses: actions/setup-python@v5
         with:
-          enable-cache: true
-
-      - name: Install dev deps
-        run: uv sync --group dev
+          python-version: "3.x"
 
       - name: Extract changelog for this version
         id: changelog
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
-          NOTES=$(uv run python -c "
+          NOTES=$(python -c "
           import re, pathlib
           text = pathlib.Path('CHANGELOG.md').read_text()
           match = re.search(