Feat/mg/initial commit state

.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

.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

.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.

.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.

.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.

.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.

.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".

.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.