github: Update agents and instructions

Author: antonsynd

.github/agents.md

@@ -57,7 +57,7 @@ Specialized agents for Sharpy development. Each agent has domain expertise and c
 
 ```bash
 dotnet build sharpy.sln && dotnet test               # Build + test
-dotnet format                                         # Format before commit
+dotnet format whitespace                             # Format before commit
 dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
 python3 -c "..."                                     # Verify Python behavior
 ```

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

@@ -21,7 +21,7 @@ Keeps documentation synchronized with implementation.
 ```bash
 # Test code blocks from docs
 for file in examples/*.spy; do
-    dotnet run --project src/Sharpy.Cli -- check "$file"
+    dotnet run --project src/Sharpy.Cli -- build "$file"
 done
 ```
 

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

@@ -10,11 +10,11 @@ Validates factual accuracy of claims. **Read-only.**
 
 ## Verification Categories
 
-1. **.NET API** — dotnet script -e "..." to verify behavior
-2. **Roslyn API** — Check SyntaxFactory method exists
-3. **Python semantics** — python3 -c "..." to verify
+1. **.NET API** — Create test program or use `csharp` REPL to verify behavior
+2. **Roslyn API** — Check SyntaxFactory method exists in docs or via test
+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/
+5. **Sharpy implementation** — `grep -r "feature" src/`
 
 ## Output Format
 

.github/agents/implementer.agent.md

@@ -37,7 +37,7 @@ For new language features:
 
 ```bash
 dotnet build sharpy.sln && dotnet test   # Build + test
-dotnet format                             # Format before commit
+dotnet format whitespace                 # Format before commit
 python3 -c "..."                         # Verify Python behavior
 dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
 ```

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

@@ -10,7 +10,7 @@ Specializes in the Sharpy parser. Handles EBNF grammar translation, AST node con
 
 ## Scope
 
-**Owns:** `src/Sharpy.Compiler/Parser/` and `src/Sharpy.Compiler/Ast/`
+**Owns:** `src/Sharpy.Compiler/Parser/` (including `Parser/Ast/`)
 
 **Does NOT modify:** Lexer, Semantic, CodeGen, or Sharpy.Core
 

.github/copilot-instructions.md

@@ -29,7 +29,7 @@ Source (.spy) → Lexer → Parser (AST) → Semantic → ValidationPipeline →
 ```bash
 dotnet build sharpy.sln                              # Build all
 dotnet test                                          # Run all tests
-dotnet format                                        # Format before committing
+dotnet format whitespace                             # Format before committing
 dotnet run --project src/Sharpy.Cli -- run file.spy # Compile and execute
 dotnet run --project src/Sharpy.Cli -- emit csharp file.spy  # Debug codegen
 dotnet run --project src/Sharpy.Cli -- emit ast file.spy     # Debug parser
@@ -117,4 +117,4 @@ $"return {value};"
 
 ## CI/CD
 
-`.github/workflows/`: `dotnet9.yml`, `dotnet10.yml` (tests on both .NET 9 and 10).
+`.github/workflows/`: `dotnet10.yml` (tests on .NET 10).

.github/instructions/README.md

@@ -35,4 +35,4 @@ For new language features, touch these components in order:
 
 Language specification lives in `docs/language_specification/`. Always check specs before implementing.
 
-See [../.github/copilot-instructions.md](../copilot-instructions.md) for repository-wide guidance.
+See [copilot-instructions.md](../copilot-instructions.md) for repository-wide guidance.

.github/instructions/Sharpy.Compiler.Tests/HOW_TO_CONTRIBUTE.instructions.md

@@ -1,3 +1,4 @@
+````instructions
 # Sharpy.Compiler.Tests
 
 Compiler test suite. Location: `src/Sharpy.Compiler.Tests/`
@@ -93,12 +94,6 @@ var result = helper.Compile();
 | `errors/` | Expected compilation failures (`.error` files) |
 | `imports/` | Module imports |
 | `generics/` | Generic types and functions |
-        var result = CompileAndExecute("print(42)");
-        Assert.True(result.Success);
-        Assert.Equal("42\n", result.StandardOutput);
-    }
-}
-```
 
 ## File-Based Tests
 
@@ -115,3 +110,5 @@ TestFixtures/
 ```bash
 dotnet test --filter "FullyQualifiedName~FileBasedIntegrationTests"
 ```
+
+````

.github/instructions/Sharpy.Core/HOW_TO_CONTRIBUTE.instructions.md

@@ -1,3 +1,4 @@
+````instructions
 # Sharpy.Core
 
 Standard library with Pythonic APIs for .NET. Location: `src/Sharpy.Core/`
@@ -22,22 +23,23 @@ Standard library with Pythonic APIs for .NET. Location: `src/Sharpy.Core/`
 
 ## Adding a Builtin Function
 
-Add to `partial class Exports` (split across files):
-```csharp
-// NewFunction.cs
-namespace Sharpy.Core;
-
-public static partial class Exports
-{
-    public static TResult NewFunction<T, TResult>(T input) => ...;
-}
-```
+1. **Add to `partial class Exports`** (split across files):
+   ```csharp
+   // NewFunction.cs
+   namespace Sharpy.Core;
 
-Then:
-```bash
-python3 -c "print(new_function(...))"  # Verify expected behavior
-dotnet test --filter "FullyQualifiedName~NewFunctionTests"
-```
+   public static partial class Exports
+   {
+       public static TResult NewFunction<T, TResult>(T input) => ...;
+   }
+   ```
+2. **Verify expected behavior against Python:**
+   ```bash
+   python3 -c "print(new_function(...))"
+   ```
+3. **Add tests** in `Sharpy.Core.Tests/NewFunctionTests.cs`
+4. **Test against Python** to verify behavior matches
+5. **Document** in language reference if needed
 
 ## Python-style Indexing Pattern
 
@@ -73,28 +75,24 @@ dotnet test --filter "FullyQualifiedName~DictTests"
 ```
 
 **CRITICAL:** Always verify behavior against `python3 -c "..."` first. Fix bugs, don't change test expectations.
-   ```
-3. **Add tests** in `Sharpy.Core.Tests/NewFunctionTests.cs`
-4. **Test against Python** to verify behavior matches
-5. **Document** in language reference if needed
 
-### Adding a New Collection Method
+## Adding a New Collection Method
 
 1. **Add method to partial class** (e.g., in `Partial.List/`)
-2. **Follow Python semantics** - check Python documentation
+2. **Follow Python semantics** — check Python documentation
 3. **Add comprehensive tests**
 4. **Test edge cases** (empty, single-element, etc.)
 5. **Update documentation** if it's a public API
 
-### Implementing an Operator Protocol
+## Implementing an Operator Protocol
 
 1. **Define interface** (e.g., `INewOperator.cs`)
 2. **Implement on relevant types**
 3. **Add operator overload** if appropriate
 4. **Test with multiple types**
 5. **Document protocol** in specs
 
-### Fixing a Bug
+## Fixing a Bug
 
 1. **Write a test that reproduces the bug:**
    ```csharp
@@ -114,77 +112,15 @@ dotnet test --filter "FullyQualifiedName~DictTests"
 
 ## Performance Considerations
 
-- **Minimize allocations** - Reuse collections where possible
-- **Use struct for small value types** - `Index`, `Slice`
-- **Lazy evaluation** - Use iterators instead of materializing lists
-- **Leverage .NET BCL** - Don't reinvent optimized data structures
-
-## Dependencies
-
-- **.NET 9.0/10.0** - BCL and runtime
-- **System.Collections.Generic** - Underlying collection types
-- **System.Linq** - Query operations
+- **Minimize allocations** — Reuse collections where possible
+- **Use struct for small value types** — `Index`, `Slice`
+- **Lazy evaluation** — Use iterators instead of materializing lists
+- **Leverage .NET BCL** — Don't reinvent optimized data structures
 
 ## Related Documentation
 
 - **Main README:** `README.md` (repository root)
 - **Core Tests Guide:** `.github/instructions/Sharpy.Core.Tests/HOW_TO_CONTRIBUTE.instructions.md`
-- **Type System Spec:** `docs/specs/type_system.md`
-- **Builtins Reference:** `docs/specs/builtins.md`
-
-## Example: Adding a New List Method
-
-Let's add `list.insert_all(index, items)` to insert multiple items at once:
-
-### 1. Implementation
-```csharp
-// In Partial.List/List.Mutation.cs
-public void InsertAll(int index, IEnumerable<T> items)
-{
-    var actualIndex = index < 0 ? _inner.Count + index : index;
-    if (actualIndex < 0) actualIndex = 0;
-    if (actualIndex > _inner.Count) actualIndex = _inner.Count;
-
-    _inner.InsertRange(actualIndex, items);
-}
-```
-
-### 2. Tests
-```csharp
-// In Sharpy.Core.Tests/Partial.ListTests/ListTests.Mutation.cs
-[Fact]
-public void TestInsertAll_InMiddle()
-{
-    var list = new List<int> { 1, 2, 5, 6 };
-    list.InsertAll(2, new[] { 3, 4 });
-    Assert.Equal(new[] { 1, 2, 3, 4, 5, 6 }, list);
-}
-
-[Fact]
-public void TestInsertAll_NegativeIndex()
-{
-    var list = new List<int> { 1, 4, 5 };
-    list.InsertAll(-2, new[] { 2, 3 });
-    Assert.Equal(new[] { 1, 2, 3, 4, 5 }, list);
-}
-
-[Fact]
-public void TestInsertAll_Empty()
-{
-    var list = new List<int> { 1, 2 };
-    list.InsertAll(1, Array.Empty<int>());
-    Assert.Equal(new[] { 1, 2 }, list);
-}
-```
-
-### 3. Verify
-```bash
-dotnet test --filter "FullyQualifiedName~TestInsertAll"
-```
-
-## Getting Help
+- **Language Specification:** `docs/language_specification/`
 
-- Check Python documentation for expected behavior
-- Review existing implementations for patterns
-- Run tests frequently to catch issues early
-- Consult type system documentation for type-related questions
+````

.github/instructions/samples/HOW_TO_CONTRIBUTE.instructions.md

@@ -100,10 +100,13 @@ dotnet test --filter "FullyQualifiedName~Integration"
 
 ```bash
 # Emit tokens to debug lexer issues
-dotnet run --project src/Sharpy.Cli -- samples/problem.spy --emit-tokens
+dotnet run --project src/Sharpy.Cli -- emit tokens samples/problem.spy
+
+# Emit AST to debug parser issues
+dotnet run --project src/Sharpy.Cli -- emit ast samples/problem.spy
 
 # Check for detailed error messages
-dotnet run --project src/Sharpy.Cli -- samples/problem.spy 2>&1 | less
+dotnet run --project src/Sharpy.Cli -- build samples/problem.spy 2>&1 | less
 ```
 
 ## Sample Categories