Improve Copilot contributor guidance and request scaffolding

.github/ISSUE_TEMPLATE/copilot-ask.md

@@ -0,0 +1,43 @@
+---
+name: Copilot Ask
+about: Request a feature, fix, or refactor using Copilot
+title: "[COPILOT] "
+labels: copilot
+---
+
+## What should Copilot do?
+
+[Clear description: implement, fix, refactor, review, etc.]
+
+## Constraints
+
+- [ ] Preserve backward compatibility
+- [ ] No changes to public API
+- [ ] Keep to one file/module
+- [ ] Minimal change (preserve existing behavior)
+- [ ] Reuse existing fixtures and patterns
+
+## Acceptance Criteria
+
+- [ ] All checks pass (`ruff check`, `ruff format`, `mypy`, `pytest`)
+- [ ] Coverage maintained ≥95% (or specify affected files)
+- [ ] Tests added/updated for changed code
+- [ ] Follows conventions: enum `_missing_`, input normalization, XML parsing guards
+
+## Context
+
+[Paste relevant code, architecture notes, error traces, or API documentation]
+
+## Verification Command
+
+```bash
+# Run these after Copilot work:
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy axis
+uv run pytest tests/test_<area>.py -v --cov=axis.<area> --cov-report=term-missing
+```
+
+## Related Issues
+
+Relates to #[issue number] (if applicable)

.github/agents/axis-review-verify.agent.md

@@ -20,6 +20,28 @@
 - For code review, use the `Axis Review` agent.
 
 **See also:** `.github/copilot-instructions.md`, `CONTRIBUTING.md`.
+
+## When to Use This Agent
+
+**Invoke with these keywords:**
+- "verify my PR"
+- "validate my changes"
+- "run checks"
+- "is my PR ready for merge?"
+- "test and review"
+- "@axis-review-verify"
+
+**Best for:**
+- Before pushing to GitHub or opening a PR
+- Full validation of code + tests + lint + type checking
+- Confirmation that all checks will pass
+- Finding failures and explaining what went wrong
+
+**Do NOT use for:**
+- Quick code review only (use Axis Review instead)
+- Sweeping repo-wide tests (specify affected test files: `tests/test_<area>.py`)
+- General questions or debugging (use default agent)
+- Exploratory questions about the codebase
 ---
 description: "Use when reviewing Axis changes and you want findings plus command-backed validation. Keywords: review with tests, verify PR, run targeted checks, regression verification, lint/type/test confirmation."
 name: "Axis Review Verify"

.github/agents/axis-review.agent.md

@@ -32,6 +32,26 @@ user-invocable: true
 
 **See also:** `.github/copilot-instructions.md`, `CONTRIBUTING.md`.
 
+## When to Use This Agent
+
+**Invoke with these keywords:**
+- "review my code"
+- "review for regressions"
+- "check for bugs"
+- "code review"
+- "@axis-review"
+
+**Best for:**
+- After writing code but before running full test suite
+- Checking enum fallbacks, XML parsing, handler phases
+- Identifying test gaps or missing edge cases
+- Risk analysis on PR changes
+
+**Do NOT use for:**
+- Running tests or lint checks (use Axis Review Verify for that)
+- General questions about the codebase (use default agent)
+- "Run pytest" or "verify CI" (specify Axis Review Verify instead)
+
 ## Scope
 - Review code changes and nearby context for defects and unintended behavior changes.
 - Prioritize runtime correctness, API/contract compatibility, and edge-case handling.