From 9056dd248b0a912fceca95b74e52df44e599582d Mon Sep 17 00:00:00 2001 From: galuszkm Date: Sun, 12 Apr 2026 07:11:59 +0200 Subject: [PATCH] chore: add copilot agents, skills, and path-specific instructions --- .../{developer.md => developer.agent.md} | 20 ++++++- .../{docs-writer.md => docs-writer.agent.md} | 16 +++++ .../agents/{reviewer.md => reviewer.agent.md} | 15 +++++ .github/agents/{tester.md => tester.agent.md} | 14 +++++ .github/copilot-instructions.md | 31 ++++++++++ .github/instructions/docs.instructions.md | 14 +++++ .github/instructions/examples.instructions.md | 15 +++++ .github/instructions/source.instructions.md | 16 +++++ .github/instructions/tests.instructions.md | 19 ++++++ .github/skills/check-and-test/SKILL.md | 46 ++++++++++++++ .github/skills/strands-api-lookup/SKILL.md | 60 +++++++++++++++++++ .github/workflows/ci.yml | 10 +--- .github/workflows/publish.yml | 11 ++-- AGENTS.md | 31 ++++++++++ 14 files changed, 302 insertions(+), 16 deletions(-) rename .github/agents/{developer.md => developer.agent.md} (68%) rename .github/agents/{docs-writer.md => docs-writer.agent.md} (76%) rename .github/agents/{reviewer.md => reviewer.agent.md} (79%) rename .github/agents/{tester.md => tester.agent.md} (72%) create mode 100644 .github/instructions/docs.instructions.md create mode 100644 .github/instructions/examples.instructions.md create mode 100644 .github/instructions/source.instructions.md create mode 100644 .github/instructions/tests.instructions.md create mode 100644 .github/skills/check-and-test/SKILL.md create mode 100644 .github/skills/strands-api-lookup/SKILL.md diff --git a/.github/agents/developer.md b/.github/agents/developer.agent.md similarity index 68% rename from .github/agents/developer.md rename to .github/agents/developer.agent.md index 0c91d9f..5fe9964 100644 --- a/.github/agents/developer.md +++ b/.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 diff --git a/.github/agents/docs-writer.md b/.github/agents/docs-writer.agent.md similarity index 76% rename from .github/agents/docs-writer.md rename to .github/agents/docs-writer.agent.md index 2343fa5..4c79163 100644 --- a/.github/agents/docs-writer.md +++ b/.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. diff --git a/.github/agents/reviewer.md b/.github/agents/reviewer.agent.md similarity index 79% rename from .github/agents/reviewer.md rename to .github/agents/reviewer.agent.md index 990f8bc..61f234d 100644 --- a/.github/agents/reviewer.md +++ b/.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. diff --git a/.github/agents/tester.md b/.github/agents/tester.agent.md similarity index 72% rename from .github/agents/tester.md rename to .github/agents/tester.agent.md index 6d5d366..b35d9ae 100644 --- a/.github/agents/tester.md +++ b/.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. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index decb91f..38419cf 100644 --- a/.github/copilot-instructions.md +++ b/.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` | diff --git a/.github/instructions/docs.instructions.md b/.github/instructions/docs.instructions.md new file mode 100644 index 0000000..1740dd2 --- /dev/null +++ b/.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. diff --git a/.github/instructions/examples.instructions.md b/.github/instructions/examples.instructions.md new file mode 100644 index 0000000..5f7e7e2 --- /dev/null +++ b/.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. diff --git a/.github/instructions/source.instructions.md b/.github/instructions/source.instructions.md new file mode 100644 index 0000000..b148f13 --- /dev/null +++ b/.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. diff --git a/.github/instructions/tests.instructions.md b/.github/instructions/tests.instructions.md new file mode 100644 index 0000000..f0ddf01 --- /dev/null +++ b/.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___`. +- 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%. diff --git a/.github/skills/check-and-test/SKILL.md b/.github/skills/check-and-test/SKILL.md new file mode 100644 index 0000000..4d5a722 --- /dev/null +++ b/.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. diff --git a/.github/skills/strands-api-lookup/SKILL.md b/.github/skills/strands-api-lookup/SKILL.md new file mode 100644 index 0000000..958c865 --- /dev/null +++ b/.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. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 67c7d0a..6de66b3 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index a18f1da..80b768d 100644 --- a/.github/workflows/publish.yml +++ b/.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( diff --git a/AGENTS.md b/AGENTS.md index 5cd587c..a6a7c35 100644 --- a/AGENTS.md +++ b/AGENTS.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` |