Add .github/copilot-instructions.md with coding conventions and validation commands

[dgenio]

Why

.github/copilot-instructions.md is the officially supported mechanism for providing repository-level coding instructions to GitHub Copilot (Chat, Completions, Coding Agent, and Code Review). Without it, Copilot has no project-specific guidance on coding style, testing patterns, import organization, or validation commands.

This file complements AGENTS.md (#51) — AGENTS.md provides architecture context; copilot-instructions.md provides coding conventions and behavioral rules scoped to Copilot specifically.

Scope / Proposed changes

Create:

• .github/copilot-instructions.md (≤120 lines)

The .github/ directory already exists (contains workflows/).

Proposed contents

The file should cover these sections:

1. Header

# Copilot Instructions — ChainWeaver

These instructions apply to all Copilot interactions in this repository.
For full architecture context and decision rationale, see [AGENTS.md](/AGENTS.md).

2. Language & runtime

## Language & runtime
- Python 3.10+ (target version for all code)
- `from __future__ import annotations` at the top of every module
- Type annotations on all function signatures (this is a `py.typed` package)

3. Code style (enforced by Ruff)

## Code style
- Formatter: `ruff format` (line length 99, double quotes, trailing commas)
- Linter: `ruff check` with rule sets: E, W, F, I, UP, B, SIM, RUF
- Import order: `isort`-compatible via Ruff's `I` rules (known first-party: `chainweaver`)
- Naming: snake_case for functions/variables, PascalCase for classes
- Docstrings: Google style (Args/Returns/Raises sections)

4. Architecture rules

## Architecture rules
- All data models use `pydantic.BaseModel` (pydantic v2 API)
- All exceptions inherit from `ChainWeaverError` (in `chainweaver/exceptions.py`)
- All public symbols must be listed in `chainweaver/__init__.py` `__all__`
- `executor.py` is deterministic — no LLM calls, no network I/O, no randomness
- Tool functions: `fn(validated_input: BaseModel) -> dict[str, Any]`

5. Testing conventions

## Testing
- Framework: `pytest` (no unittest)
- Test files: `tests/test_*.py`
- Use `@pytest.fixture()` for shared objects (tools, flows, executors)
- Test both success and error paths
- Assertions: use plain `assert` (pytest rewrites them), not `self.assertEqual`
- No mocking of internal ChainWeaver classes unless testing integration boundaries

6. Validation commands

## Validation commands (run before every commit/PR)
```bash
# Full validation suite (copy-paste ready)
ruff check chainweaver/ tests/ examples/
ruff format --check chainweaver/ tests/ examples/
python -m pytest tests/ -v

When #39 (mypy) lands, add: python -m mypy chainweaver/

### 7. PR conventions

```markdown
## PR conventions
- One logical change per PR
- PR title: imperative mood (e.g., "Add retry logic to executor")
- If you change architecture (add/remove/rename modules), update AGENTS.md in the same PR
- If you change coding conventions, update this file in the same PR

8. What NOT to do

## Anti-patterns (never generate these)
- Do NOT add LLM/AI client calls to `executor.py`
- Do NOT use `unittest.TestCase` — use plain pytest functions/classes
- Do NOT import from `chainweaver` internals using relative paths outside the package
- Do NOT add dependencies without updating `pyproject.toml` `[project.dependencies]`
- Do NOT commit secrets, API keys, or credentials

Labels to apply

• documentation
• priority:P1
• ai-friendly
• milestone:v0.1.0

Depends on

• Add AGENTS.md with architecture map, decision context, and agent guardrails #51 — AGENTS.md must exist first (copilot-instructions.md references it)

Related existing issues

• Add AGENTS.md, .github/copilot-instructions.md, and CONTRIBUTING.md #40 — proposed copilot-instructions.md. This issue supersedes the copilot-instructions.md portion of Add AGENTS.md, .github/copilot-instructions.md, and CONTRIBUTING.md #40 with a more detailed, best-practice-aligned specification.

Acceptance criteria

• .github/copilot-instructions.md exists
• File is ≤120 lines
• File links to AGENTS.md for architecture context (not duplicated)
• Ruff config cited matches pyproject.toml [tool.ruff] section
• Validation commands match CI pipeline (.github/workflows/ci.yml)
• No architecture map or decision context (those live in AGENTS.md)
• Anti-patterns section included

Avoid drift/duplication notes

• Coding conventions are canonical here — not in AGENTS.md or README.
• Architecture context is canonical in AGENTS.md — copilot-instructions.md links to it.
• Ruff config is canonical in pyproject.toml — copilot-instructions.md summarizes it for quick agent context but defers to pyproject.toml as source of truth.
• If Ruff rules change in pyproject.toml, this file must be updated in the same PR.

References

• GitHub Docs: Adding copilot-instructions.md
• Add AGENTS.md with architecture map, decision context, and agent guardrails #51 — AGENTS.md
• Add AGENTS.md, .github/copilot-instructions.md, and CONTRIBUTING.md #40 — Original proposal (superseded)