chore: refine .github templates for AI collaboration

.github/ISSUE_TEMPLATE/agent-task.md

@@ -0,0 +1,52 @@
+---
+name: Agent Task
+about: Use this template for issues intended for AI assistants like Copilot coding agent
+---
+name: Agent Task
+about: Issue template for tasks intended for AI assistants (Copilot, agents)
+title: "[AGENT] "
+labels: ["agent", "triage"]
+assignees: []
+---
+
+## Summary
+
+One-line summary of the task.
+
+## Goal
+
+Describe the expected outcome when this issue is done.
+
+## Acceptance Criteria (required)
+
+Make this list precise and testable — agents complete best with concrete checks.
+
+- [ ] Unit tests added and passing (include how to run)
+- [ ] Lint/format checks pass (describe commands)
+- [ ] Behavior validated for edge cases (give examples)
+- [ ] Changes limited to allowed paths below
+
+> Tip: add example input/output or a small reproducible snippet when applicable.
+
+## Scope & Constraints
+
+- Allowed: `src/`, `lib/`, `tests/`
+- Avoid: `infra/`, `configs/`, `scripts/`
+- Runtime / compatibility constraints (e.g. Node/Python versions)
+- Performance / memory constraints (if relevant)
+
+## Suggested Sub-tasks (optional)
+
+1. Add/modify implementation in `src/`
+2. Add unit tests in `tests/`
+3. Run linters and fix issues
+4. Update docs / changelog
+
+## Clarifying notes for the agent
+
+- If requirements are ambiguous, ask up to 3 clarifying questions before changing code.
+- Keep changes minimal and reversible; prefer small commits.
+
+## Related
+
+Links to specs, designs, or reference issues/PRs

.github/ISSUE_TEMPLATE/plan-issue.md

@@ -0,0 +1,27 @@
+---
+name: Agent Plan
+about: High-level planning before breaking work into smaller agent tasks
+title: "[PLAN] "
+labels: ["agent", "planning"]
+assignees: []
+---
+
+## Objective
+
+One-paragraph description of the overall goal and why it matters.
+
+## Success Criteria
+
+- Clear deliverables (components, APIs)
+- Acceptance criteria for derived tasks defined
+
+## Milestones / Rough Plan
+
+1. Research & decisions (dependencies, constraints)
+2. Design major components and interfaces
+3. Implementation (split into small, testable issues)
+4. Testing & verification
+
+## Next steps
+
+- Create atomic `agent` issues for each implementation task with clear acceptance criteria.

.github/PULL_REQUEST_TEMPLATE/agent-pr.md

@@ -0,0 +1,25 @@
+---
+name: Agent PR
+about: PR template for changes produced by AI agents
+---
+
+## Summary
+
+One-line summary of the change and why it was made.
+
+## Checklist
+
+- [ ] Linked to an `agent` issue with clear acceptance criteria
+- [ ] Tests added or updated and passing (include how to run)
+- [ ] CI green / linting passed
+- [ ] Changes limited to allowed paths from the linked issue
+- [ ] Docs / changelog updated (if applicable)
+
+## How to validate
+
+1. Run tests and linters described in the linked issue
+2. Manual verification steps (if applicable)
+
+## Notes for reviewers
+
+If produced by an AI agent, add clear, actionable feedback and request precise follow-up changes.

.github/copilot-instructions.md

@@ -0,0 +1,34 @@
+# Project Instructions for AI Assistants
+
+Purpose: give concise, repository-level guidance so agents produce reviewable, testable work.
+
+Basic rules
+
+- Follow repository linters and formatters before opening PRs (run commands listed below).
+- Prefer small, focused changes with one responsibility per issue/PR.
+- Always add or update tests for behavioral changes; include commands to run them.
+- Limit edits to paths listed in the issue `Scope & Constraints`.
+- Preserve backwards compatibility unless the issue explicitly requests a breaking change.
+
+Agent workflow specifics
+
+- Link the originating `agent` issue in the PR body and reference acceptance criteria.
+- If task requirements are ambiguous, ask up to 3 clarifying questions before modifying code.
+- Keep diffs minimal and reversible; prefer multiple small PRs over a single large one.
+- When changing APIs, include migration notes and update docs/changelog.
+
+Local verification (examples)
+
+```bash
+# JS/Node projects
+npm ci && npm test && npm run lint
+
+# Python projects
+python -m pip install -r requirements-dev.txt
+pytest
+flake8
+```
+
+If the repository uses other tooling, include equivalent commands in the issue body.
+
+If you are an agent: prefer explicit, test-driven changes and surface any uncertainties as questions in the issue or PR.

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Run Node checks (if package.json present)
+        shell: bash
+        run: |
+          set -e
+          run_node() {
+            echo "Found package.json at $1"
+            pushd "$1" >/dev/null
+            if [ -f package-lock.json ]; then npm ci; else npm install || true; fi
+            if npm run -s lint >/dev/null 2>&1; then npm run lint || true; fi
+            if npm test --silent >/dev/null 2>&1; then npm test || true; fi
+            popd >/dev/null
+          }
+          if [ -f package.json ]; then run_node .; fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Run Python checks (if requirements or pyproject present)
+        shell: bash
+        run: |
+          set -e
+          run_py() {
+            echo "Python project at $1"
+            pushd "$1" >/dev/null
+            if [ -f requirements-dev.txt ]; then python -m pip install -r requirements-dev.txt; fi
+            if [ -f pyproject.toml ]; then python -m pip install -e .; fi
+            if python -m flake8 --version >/dev/null 2>&1; then python -m flake8 || true; fi
+            if python -m pytest -q >/dev/null 2>&1; then python -m pytest -q || true; fi
+            popd >/dev/null
+          }
+          if [ -f requirements-dev.txt ] || [ -f pyproject.toml ]; then run_py .; fi

README.md

@@ -0,0 +1,22 @@
+# AI Collaboration Template
+
+This repository contains a lightweight template for assigning, tracking, and iterating work intended for AI assistants (e.g., Copilot coding agents).
+
+Contents:
+- `.github/ISSUE_TEMPLATE/agent-task.md` — primary issue template for agent tasks
+- `.github/copilot-instructions.md` — repository-level guidance for AI assistants
+- `.github/ISSUE_TEMPLATE/plan-issue.md` — a plan-style issue template for complex work
+- `.github/PULL_REQUEST_TEMPLATE/agent-pr.md` — PR checklist for agent-generated PRs
+
+How to use:
+
+1. Create small, testable issues using the `agent-task` template.
+2. Attach acceptance criteria and allowed file paths to limit scope.
+3. Require tests and CI checks to validate agent output.
+
+Iterating the templates:
+
+- After each agent-driven PR, update the templates with examples and clarifications that improved results.
+- Add project-specific rules to `.github/copilot-instructions.md` so AI follows team conventions.
+
+This template is minimal — adapt and expand it to match your stack and workflows.