Add PR template, YAML issue forms, and CONTRIBUTING.md

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in ChainWeaver.
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the issue.
+      placeholder: |
+        1. Create a Flow with ...
+        2. Call executor.execute_flow(...)
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include full tracebacks where relevant.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: python_version
+    attributes:
+      label: Python version
+      options:
+        - "3.10"
+        - "3.11"
+        - "3.12"
+        - "3.13"
+    validations:
+      required: true
+
+  - type: input
+    id: chainweaver_version
+    attributes:
+      label: ChainWeaver version
+      placeholder: "e.g. 0.1.0"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional context
+      description: Any other context, screenshots, or relevant information.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature Request
+description: Propose a new feature or enhancement for ChainWeaver.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the feature you'd like to see.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use case
+      description: What problem does this solve? Describe the scenario where this feature would be useful.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed_solution
+    attributes:
+      label: Proposed solution
+      description: How would you like this feature to work? Include API sketches or examples if possible.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other approaches did you consider? Why is your proposed solution preferable?
+    validations:
+      required: false

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## Summary
+
+
+## Changes
+
+- 
+
+## Testing
+
+- [ ] Linting passes (`ruff check chainweaver/ tests/ examples/`)
+- [ ] Formatting check passes (`ruff format --check chainweaver/ tests/ examples/`)
+- [ ] Type checking passes (`python -m mypy chainweaver/`)
+- [ ] All existing tests pass (`python -m pytest tests/ -v`)
+- [ ] New tests added for new functionality
+
+## Related Issues
+
+
+## Checklist
+- [ ] Code follows project conventions (see `AGENTS.md` and `docs/agent-context/`)
+- [ ] Public API changes are documented
+- [ ] No secrets or credentials included

CONTRIBUTING.md

@@ -0,0 +1,114 @@
+# Contributing to ChainWeaver
+
+Thank you for your interest in contributing to ChainWeaver!
+This guide covers everything you need to get started, whether you are a human contributor or an AI agent.
+
+For AI contributors: also read [`AGENTS.md`](AGENTS.md) and [`docs/agent-context/`](docs/agent-context/), which contain agent-specific conventions. `.github/copilot-instructions.md` is a thin wrapper that points to the same sources.
+
+---
+
+## Table of Contents
+
+- [Dev environment setup](#dev-environment-setup)
+- [Running tests](#running-tests)
+- [Code style](#code-style)
+- [PR process](#pr-process)
+- [Reporting issues](#reporting-issues)
+
+---
+
+## Dev environment setup
+
+```bash
+# Clone the repository
+git clone https://github.com/dgenio/ChainWeaver.git
+cd ChainWeaver
+
+# Create a virtual environment
+python -m venv .venv
+# Windows
+.venv\Scripts\activate
+# Linux/macOS
+# source .venv/bin/activate
+
+# Install with dev dependencies (editable mode)
+pip install -e ".[dev]"
+```
+
+Python 3.10 or later is required.
+
+---
+
+## Running tests
+
+Run the full test suite:
+
+```bash
+python -m pytest tests/ -v
+```
+
+Run all four validation commands before every commit:
+
+```bash
+ruff check chainweaver/ tests/ examples/
+ruff format --check chainweaver/ tests/ examples/
+python -m mypy chainweaver/
+python -m pytest tests/ -v
+```
+
+CI runs lint + format + mypy on Python 3.10, and tests across Python 3.10–3.13.
+
+---
+
+## Code style
+
+- **Type annotations are required** on all function signatures.
+- **Pydantic `BaseModel`** for all data schemas (tool I/O, `Flow`, `FlowStep`).
+- `from __future__ import annotations` at the top of every module.
+- Single runtime dependency: `pydantic>=2.0`. Add new runtime dependencies judiciously — only when they deliver clear value and are well-maintained. Always update `pyproject.toml` `[project.dependencies]`.
+- All public symbols must be exported in `chainweaver/__init__.py` `__all__`.
+- All exceptions must inherit from `ChainWeaverError`.
+- Ruff is the linter and formatter — run `ruff check` and `ruff format --check` before committing.
+
+### Vocabulary
+
+Use the canonical terms consistently in code, docs, and PR descriptions:
+
+| Use | Never use |
+|-----|-----------|
+| **flow** | chain, pipeline |
+| **tool** | function, action (when referring to a `Tool` instance) |
+
+---
+
+## PR process
+
+1. **One logical change per PR.** A PR that implements a feature, adds tests, and updates docs is one logical change. Only split if changes are genuinely unrelated.
+2. **Link the relevant issue** in your PR description under _Related Issues_.
+3. **All tests must pass** before requesting review.
+4. **Branch naming:** `{type}/{issue_number}-{short-description}`
+   - Types: `feat`, `fix`, `docs`, `test`, `refactor`
+   - Example: `feat/55-add-pr-template`
+5. **Commit messages** follow [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add timeout guardrails to tool execution
+   fix: correct input mapping for literal constants
+   docs: update architecture map after log_utils rename
+   ```
+6. Fill in all sections of the PR template (Summary, Changes, Testing, Related Issues, Checklist).
+7. Do not include secrets, API keys, credentials, or PII in code, logs, or tests.
+
+---
+
+## Reporting issues
+
+Use the GitHub issue forms:
+
+- **Bug report** — unexpected behavior, errors, or incorrect output.
+- **Feature request** — new capabilities or enhancements.
+
+Provide as much context as possible: Python version, ChainWeaver version, a minimal reproduction, and the full traceback where relevant.
+
+---
+
+For the full set of agent-oriented conventions, invariants, and architecture decisions, see [`AGENTS.md`](AGENTS.md) and [`docs/agent-context/`](docs/agent-context/).