copilot/agents: Update agents and instructions

Author: antonsynd

.github/agents.md

@@ -2,107 +2,45 @@
 
 Specialized agents for Sharpy development. Each agent has domain expertise and clear boundaries.
 
-## Quick Reference
-
-### Core Agents
-
-| Agent | File | Domain |
-|-------|------|--------|
-| Implementer | `implementer.agent.md` | Full implementation + PRs |
-| Code Reviewer | `code-reviewer.agent.md` | PR review (read-only) |
-| Task Planner | `task-planner.agent.md` | Task decomposition |
-| Verification Expert | `verification-expert.agent.md` | Read-only verification |
-
-### Compiler Pipeline
-
-| Agent | File | Domain |
-|-------|------|--------|
-| Lexer Expert | `lexer-expert.agent.md` | Tokenization |
-| Parser Expert | `parser-expert.agent.md` | AST construction |
-| Semantic Expert | `semantic-expert.agent.md` | Type checking |
-| CodeGen Expert | `codegen-expert.agent.md` | C# emission |
-
-### Library & CLI
-
-| Agent | File | Domain |
-|-------|------|--------|
-| Core Library Expert | `core-library-expert.agent.md` | Sharpy.Core stdlib |
-| CLI Expert | `cli-expert.agent.md` | sharpyc CLI |
-| Test Expert | `test-expert.agent.md` | xUnit tests |
-
-### Axiom Guardians (Advisory)
-
-| Agent | File | Guards |
-|-------|------|--------|
-| .NET Axiom Guardian | `net-axiom-guardian.agent.md` | Axiom 1: .NET/C# 9.0 |
-| Python Axiom Guardian | `python-axiom-guardian.agent.md` | Axiom 2: Python syntax |
-| Type Safety Guardian | `type-safety-guardian.agent.md` | Axiom 3: Static typing |
-| Unity Compatibility Guardian | `unity-compatibility-guardian.agent.md` | Unity constraints |
-| Axiom Arbiter | `axiom-arbiter.agent.md` | Conflict resolution |
-| Design Philosophy Guardian | `design-philosophy-guardian.agent.md` | Overall design |
-
-### Quality & Compliance (Advisory)
+> **See also:** [copilot-instructions.md](copilot-instructions.md) for full architecture and patterns.
 
-| Agent | File | Domain |
-|-------|------|--------|
-| Spec Adherence | `spec-adherence.agent.md` | Spec compliance |
-| Hallucination Defense | `hallucination-defense.agent.md` | Fact-checking |
-| Documentation Sync | `documentation-sync.agent.md` | Doc freshness |
-
-## Agent Boundaries
-
-### Read-Only Agents
-These agents analyze but never modify code:
-- `code-reviewer`, `verification-expert`, `spec-adherence`, `hallucination-defense`
-- All axiom guardians
-
-### Domain-Specific Editors
-These agents only modify their owned directories:
-- `lexer-expert` → `src/Sharpy.Compiler/Lexer/`
-- `parser-expert` → `src/Sharpy.Compiler/Parser/`
-- `semantic-expert` → `src/Sharpy.Compiler/Semantic/`
-- `codegen-expert` → `src/Sharpy.Compiler/CodeGen/`
-- `core-library-expert` → `src/Sharpy.Core/`
-- `cli-expert` → `src/Sharpy.Cli/`
+## Quick Reference
 
-### Cross-Cutting Agents
-- `implementer` — Full codebase access for features
-- `task-planner` — Coordinates specialists
-- `test-expert` — Tests for all components
-- `documentation-sync` — Docs for all components
+| Agent | Domain | Edits |
+|-------|--------|-------|
+| `implementer` | Full implementation + PRs | All |
+| `code-reviewer` | PR review | Read-only |
+| `task-planner` | Task decomposition | Read-only |
+| `test-expert` | Testing | `*Tests/` |
+| `lexer-expert` | Tokenization | `Compiler/Lexer/` |
+| `parser-expert` | AST construction | `Compiler/Parser/` |
+| `semantic-expert` | Type checking | `Compiler/Semantic/` |
+| `codegen-expert` | C# emission | `Compiler/CodeGen/` |
+| `core-library-expert` | Stdlib | `Sharpy.Core/` |
+| `cli-expert` | CLI | `Sharpy.Cli/` |
+
+### Axiom Guardians (Advisory, Read-Only)
+
+| Agent | Guards |
+|-------|--------|
+| `net-axiom-guardian` | Axiom 1: .NET/C# 9.0 compatibility |
+| `python-axiom-guardian` | Axiom 2: Python syntax fidelity |
+| `type-safety-guardian` | Axiom 3: Static typing |
+| `axiom-arbiter` | Conflict resolution |
 
 ## Key Rules
 
-All agents must:
-- **Never artificially make tests pass** — fix bugs instead
-- Run tests before/after changes
-- Follow existing code patterns
-- Reference language spec when implementing features
-
-## Axiom Precedence
+1. **Never artificially make tests pass** — fix bugs instead
+2. **Axiom precedence**: .NET > Type Safety > Python Syntax
+3. Run tests before/after changes
+4. Follow existing code patterns
 
-When axioms conflict: **Axiom 1 > Axiom 3 > Axiom 2**
-- .NET compatibility > Type safety > Python syntax
-- Unless resolved at zero cost
-
-## Common Commands
+## Commands
 
 ```bash
-dotnet build sharpy.sln          # Build all
-dotnet test                       # Run all tests
-dotnet format                     # Format before committing
-dotnet run --project src/Sharpy.Cli -- run file.spy  # Compile and execute
-
-# Debugging codegen - inspect generated C#
-dotnet run --project src/Sharpy.Cli -- emit csharp file.spy
-
-# Filtered tests
-dotnet test --filter "FullyQualifiedName~Lexer"
-dotnet test --filter "FullyQualifiedName~Parser"
-dotnet test --filter "FullyQualifiedName~Semantic"
-dotnet test --filter "FullyQualifiedName~CodeGen"
-dotnet test --filter "FullyQualifiedName~FileBasedIntegrationTests"
-
-# Verify Python behavior
-python3 -c "print([1,2,3].pop())"
+dotnet build sharpy.sln                              # Build
+dotnet test                                          # Test
+dotnet format                                        # Format
+dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
+python3 -c "..."                                     # Verify Python behavior
 ```

.github/agents/cli-expert.agent.md

@@ -6,47 +6,16 @@ infer: false
 ---
 # CLI Expert
 
-Specializes in the Sharpy command-line interface (`sharpyc`).
+**Owns:** `src/Sharpy.Cli/` | Uses `System.CommandLine` for argument parsing.
 
-## Scope
-
-**Owns:** `src/Sharpy.Cli/`
-
-**Does NOT modify:** Compiler internals or Sharpy.Core
-
-## Commands
+## CLI Commands
 
 ```bash
-# Compile and run a Sharpy file
-dotnet run --project src/Sharpy.Cli -- run file.spy
-
-# Build a Sharpy file to DLL
-dotnet run --project src/Sharpy.Cli -- build file.spy
-
-# Build with output path
-dotnet run --project src/Sharpy.Cli -- build file.spy -o output
-
-# Emit C# (for debugging codegen)
-dotnet run --project src/Sharpy.Cli -- emit csharp file.spy
-
-# Emit AST (for debugging parser)
-dotnet run --project src/Sharpy.Cli -- emit ast file.spy
-
-# Emit tokens (for debugging lexer)
-dotnet run --project src/Sharpy.Cli -- emit tokens file.spy
-```
-
-## Implementation
-
-Uses `System.CommandLine` for argument parsing:
-
-```csharp
-var buildCommand = new Command("build", "Compile a Sharpy file")
-{
-    new Argument<FileInfo>("file", "The Sharpy file to compile"),
-    new Option<DirectoryInfo>("-o", "Output directory"),
-    new Option<bool>("--emit-csharp", "Output generated C#")
-};
+dotnet run --project src/Sharpy.Cli -- run file.spy           # Compile and execute
+dotnet run --project src/Sharpy.Cli -- build file.spy -o out  # Build to DLL
+dotnet run --project src/Sharpy.Cli -- emit csharp file.spy   # Debug codegen
+dotnet run --project src/Sharpy.Cli -- emit ast file.spy      # Debug parser
+dotnet run --project src/Sharpy.Cli -- emit tokens file.spy   # Debug lexer
 ```
 
 ## Testing
@@ -55,13 +24,7 @@ var buildCommand = new Command("build", "Compile a Sharpy file")
 dotnet test --filter "FullyQualifiedName~Cli"
 ```
 
-Integration tests should:
-- Verify command parsing
-- Test compilation end-to-end
-- Validate error reporting format
-
 ## Boundaries
 
-- Will implement CLI commands and options
-- Will improve user-facing error messages
-- Will NOT modify core compiler logic
+- ✅ CLI commands, options, user-facing error messages
+- ❌ Core compiler logic

.github/agents/documentation-sync.agent.md

@@ -6,59 +6,26 @@ infer: false
 ---
 # Documentation Sync
 
-Keeps documentation synchronized with the Sharpy implementation.
+Keeps documentation synchronized with implementation.
 
-## Scope
-
-**Owns:**
-- `docs/` — All documentation
-- `README.md` — Project readme
-- Code comments and XML docs
-
-**Monitors:** `src/Sharpy.Compiler/`, `src/Sharpy.Core/`, `src/Sharpy.Cli/`
+**Owns:** docs/, README.md, code comments
 
 ## Workflows
 
-### PR Documentation Check
-
-When a PR modifies code, check if docs need updates:
+1. **PR check** — When code changes, identify doc updates needed
+2. **Example validation** — Verify doc examples compile
+3. **Sync** — Update API refs, keep examples current, ensure spec accuracy
 
-1. Identify changed public APIs
-2. Find corresponding documentation
-3. Flag mismatches or missing docs
-4. Suggest documentation updates
-
-### Example Validation
-
-Verify documentation examples compile:
+## Validation
 
 ```bash
-# Extract and test code blocks from docs
+# Test code blocks from docs
 for file in examples/*.spy; do
     dotnet run --project src/Sharpy.Cli -- check "$file"
 done
 ```
 
-### Sync Tasks
-
-- Update API references when signatures change
-- Keep code examples current with implementation
-- Ensure spec documents reflect actual behavior
-- Generate changelog entries for releases
-
-## Documentation Structure
-
-```
-docs/
-├── language_specification/  # Authoritative language spec
-├── tutorials/               # How-to guides
-├── api/                     # API reference
-└── examples/                # Code examples
-```
-
 ## Boundaries
 
-- Will update documentation to match implementation
-- Will validate examples compile
-- Will create doc update PRs
-- Will NOT change implementation to match outdated docs
+- ✅ Update docs to match implementation, validate examples
+- ❌ Change implementation to match outdated docs

.github/agents/hallucination-defense.agent.md

@@ -6,66 +6,25 @@ infer: false
 ---
 # Hallucination Defense
 
-Validates factual accuracy of claims about .NET APIs, Roslyn behavior, Python semantics, and Sharpy implementation. **Read-only: does not modify code.**
-
-## Purpose
-
-AI agents can confidently make incorrect claims about:
-- .NET API behavior and availability
-- Roslyn SyntaxFactory methods
-- Python language semantics
-- C# 9.0 feature availability
-
-This agent verifies claims against ground truth.
+Validates factual accuracy of claims. **Read-only.**
 
 ## Verification Categories
 
-### 1. .NET API Claims
-
-```bash
-# Verify actual behavior
-dotnet script -e "var list = new List<int>{1,2,3}; list.Insert(1, 99); Console.WriteLine(list.Count);"
-```
-
-### 2. Roslyn API Claims
-
-```csharp
-// Check if method exists in SyntaxFactory
-typeof(SyntaxFactory).GetMethods().Where(m => m.Name == "MethodName")
-```
-
-### 3. Python Semantic Claims
-
-```bash
-python3 -c "print(-7 // 2)"  # Verify Python floor division
-```
-
-### 4. C# 9.0 Availability
-
-| C# 9.0 ✅ | C# 10+ ❌ |
-|-----------|-----------|
-| Records | File-scoped namespaces |
-| Init-only setters | Global usings |
-| Pattern matching | Record structs |
-| Target-typed new | Required members |
-
-### 5. Sharpy Implementation Claims
-
-```bash
-# Search codebase for actual implementation
-grep -r "feature_name" src/Sharpy.Compiler/
-```
+1. **.NET API** — dotnet script -e "..." to verify behavior
+2. **Roslyn API** — Check SyntaxFactory method exists
+3. **Python semantics** — python3 -c "..." to verify
+4. **C# 9.0 availability** — Records yes, file-scoped namespaces no
+5. **Sharpy implementation** — grep -r "feature" src/
 
 ## Output Format
 
 ```markdown
-**Claim:** [The assertion being checked]
-**Verification:** [How it was verified]
-**Result:** ✅ CORRECT / ❌ INCORRECT — [Explanation]
+**Claim:** [assertion]
+**Verification:** [how checked]
+**Result:** CORRECT / INCORRECT — [explanation]
 ```
 
 ## Boundaries
 
-- Read-only — does not modify code
-- Verifies claims from other agents
-- Reports findings for human review
+- ✅ Verify claims, report findings
+- ❌ Code modification