docs: rewrite agent documentation system

[dgenio]

Summary

Replaces the monolithic AGENTS.md and copilot-instructions.md with a layered, cross-referenced documentation architecture designed for AI coding agents.

What changed

Canonical shared layer (docs/agent-context/) — 5 new files:

• architecture.md — module boundaries, design traps, planned modules, Weaver Stack guardrail
• workflows.md — dev commands, CI, code style, testing, PR/git conventions, new-module checklist, doc governance triggers
• invariants.md — 12 hard rules (detailed), forbidden patterns table, safe/unsafe simplifications
• lessons-learned.md — failure-capture workflow, 5 recurring mistake patterns, promotion criteria
• review-checklist.md — definition-of-done checklist organized by category (CI, correctness, testing, API, architecture, docs, vocabulary, PR hygiene)

Projection layers — 3 new files:

• .github/instructions/chainweaver.instructions.md — scoped design-trap reminders for chainweaver/**
• .github/instructions/tests.instructions.md — scoped test boundary + framework rules for tests/**
• .claude/CLAUDE.md — Claude operational entrypoint and router

Rewritten files — 2 modified:

• AGENTS.md — primary entrypoint with 12 invariants (was 10), vocabulary table, executor/flow semantics (§5), documentation map (§9), update policy (§10)
• .github/copilot-instructions.md — reduced from ~90 lines to ~45-line thin review-oriented wrapper with doc-map pointer table

Why

The previous documentation had content duplicated between AGENTS.md and copilot-instructions.md, stale references (e.g., mypy not yet landed), vocabulary inconsistencies ("chains" vs "flows"), and no structured home for invariants, lessons learned, or review checklists. This rewrite:

1. Eliminates duplication by establishing a single canonical layer with thin projections
2. Adds invariants 11–12 (CI + PR discipline) that were implicit but undocumented
3. Provides scoped instruction files that activate only on relevant file paths
4. Creates a failure-capture workflow and promotion path for agent lessons
5. Documents design traps that agents repeatedly "fix" incorrectly

Testing performed

All four validation commands pass locally:

ruff check chainweaver/ tests/ examples/        → All checks passed!
ruff format --check chainweaver/ tests/ examples/ → 13 files already formatted
python -m mypy chainweaver/                      → Success: no issues found in 7 source files
python -m pytest tests/ -v                       → 46 passed in 0.55s

No source code was modified — this is a documentation-only change.

AI agent instruction files reviewed/changed

All 5 agent instruction files in this PR are the change:

• AGENTS.md (rewritten)
• .github/copilot-instructions.md (rewritten)
• .github/instructions/chainweaver.instructions.md (new)
• .github/instructions/tests.instructions.md (new)
• .claude/CLAUDE.md (new)

Cross-references between all 10 files have been verified for consistency.

[Copilot]

Pull request overview

This PR replaces the monolithic agent instruction files (AGENTS.md and .github/copilot-instructions.md) with a layered, cross-referenced documentation architecture designed for AI coding agents. It establishes a canonical shared layer in docs/agent-context/ (5 files covering architecture, workflows, invariants, lessons learned, and review checklists), projection layers for specific tools (Copilot scoped instructions, Claude entrypoint), and rewrites the two existing files as thinner wrappers that reference the canonical layer.

Changes:

• Added 5 canonical shared documentation files in docs/agent-context/ covering architecture boundaries, development workflows, hard invariants/forbidden patterns, recurring mistake patterns, and a definition-of-done review checklist.
• Added 3 projection layer files (.github/instructions/chainweaver.instructions.md, .github/instructions/tests.instructions.md, .claude/CLAUDE.md) scoped to specific file paths or tools.
• Rewrote AGENTS.md (expanded to 12 invariants, added vocabulary table, executor/flow semantics, documentation map) and .github/copilot-instructions.md (condensed to a thin review-oriented wrapper).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/agent-context/architecture.md	New canonical reference for module boundaries, design traps, planned modules, and Weaver Stack guardrail
docs/agent-context/workflows.md	New canonical reference for dev commands, CI, code style, testing, PR/git conventions, and doc governance triggers
docs/agent-context/invariants.md	New canonical reference for 12 hard rules, forbidden patterns table, and safe/unsafe simplifications
docs/agent-context/lessons-learned.md	New failure-capture workflow with 5 recurring mistake patterns and promotion criteria
docs/agent-context/review-checklist.md	New definition-of-done checklist organized by category
AGENTS.md	Rewritten as primary entrypoint with expanded invariants, vocabulary, executor semantics, doc map, and update policy
.github/copilot-instructions.md	Reduced to thin review-oriented wrapper pointing to canonical docs
.github/instructions/chainweaver.instructions.md	New scoped design-trap reminders for chainweaver/**
.github/instructions/tests.instructions.md	New scoped test boundary and framework rules for tests/**
.claude/CLAUDE.md	New Claude operational entrypoint and router

---

You can also share your feedback on Copilot code review. Take the survey.