From 783a3119aa4dd21406f152be3f19f4d3e92800da Mon Sep 17 00:00:00 2001
From: Benjamin Abt <mail@benjamin-abt.com>
Date: Thu, 15 Jan 2026 18:06:01 +0100
Subject: [PATCH] feat(docs): add GitHub Copilot instructions

---
 .github/copilot-instructions.md | 129 ++++++++++++++++++++++++++++++++
 .vscode/tasks.json              |  56 +++++++++++---
 2 files changed, 173 insertions(+), 12 deletions(-)
 create mode 100644 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..62ffd87
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,129 @@
+# GitHub Copilot Instructions
+
+## 1. Repository Context & Mission
+
+**Repository:** `HttpUserAgentParser` (mycsharp)
+
+**Primary Goal:**  
+Provide a **high-performance, stable, and broadly compatible .NET library** for parsing HTTP User-Agent strings, including integrations for ASP.NET Core and MemoryCache.
+
+**Core Design Principles:**
+- API stability over convenience
+- Predictable performance characteristics
+- Minimal allocations in hot paths
+- Full test coverage for all observable behavior
+
+---
+
+## 2. Repository Structure (Authoritative)
+
+Copilot must understand and respect the architectural boundaries:
+
+- `src/HttpUserAgentParser`  
+  → Core parsing logic and public APIs
+
+- `src/HttpUserAgentParser.AspNetCore`  
+  → ASP.NET Core integration (middleware, extensions)
+
+- `src/HttpUserAgentParser.MemoryCache`  
+  → Caching extensions and cache-aware abstractions
+
+- `tests/*`  
+  → Unit tests for **all** shipped packages  
+  → Tests define expected behavior and are the source of truth
+
+- `perf/*`  
+  → Benchmarks for performance-sensitive code paths
+
+---
+
+## 3. Standard .NET CLI Commands
+
+Use these commands consistently:
+
+- Clean:  
+  `dotnet clean --nologo`
+
+- Restore:  
+  `dotnet restore`
+
+- Build:  
+  `dotnet build --nologo`
+
+- Test (all):  
+  `dotnet test --nologo`
+
+- Test (single project):  
+  `dotnet test <path-to-csproj> --nologo`
+
+---
+
+## 4. Autonomous Execution Rules (Critical)
+
+Copilot is expected to work **independently and end-to-end** without human intervention.
+
+### Mandatory Quality Gates (Never Skip)
+- The solution **must compile** after every change
+- **All tests must pass**
+- New behavior **must include unit tests**
+- Public APIs **must not break** existing users unless explicitly intended
+- Changes must be **minimal, focused, and intentional**
+
+If any gate fails:
+1. Diagnose the root cause
+2. Fix the issue
+3. Re-run the full validation cycle
+
+---
+
+## 5. Change Strategy & Scope Control
+
+When solving a task, Copilot should:
+
+1. **Analyze existing code first**
+   - Prefer extension over modification
+   - Reuse established patterns and helpers
+2. **Avoid architectural rewrites**
+   - No refactors unless explicitly required
+3. **Preserve backward compatibility**
+   - No breaking changes to public APIs
+   - No silent behavioral changes
+
+If multiple solutions are possible:
+- Prefer the **simplest**, **most explicit**, and **least invasive** option
+
+---
+
+## 6. Testing Requirements
+
+Every functional change must be fully tested:
+
+- Unit tests are mandatory for:
+  - New features
+  - Bug fixes
+  - Edge cases and regressions
+- Prefer existing utilities from:  
+  `tests/HttpUserAgentParser.TestHelpers`
+
+Tests define correctness. If behavior is unclear, tests take precedence over assumptions.
+
+---
+
+## 7. Performance Guidelines
+
+- Treat parsing logic as performance-critical
+- Avoid unnecessary allocations and LINQ in hot paths
+- Prefer spans, pooling, and cached results where appropriate
+- Update or add benchmarks in `perf/*` for performance-relevant changes
+
+---
+
+## 8. Output Expectations
+
+Copilot should deliver:
+- Compilable, production-ready code
+- Complete test coverage for new behavior
+- Clear, intentional commits without unrelated changes
+
+**Do not stop early.**  
+A task is only complete when **all quality gates pass** and the solution is fully validated.
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index 5ddca9a..9b69370 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -1,13 +1,45 @@
 {
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"label": "test",
-			"type": "shell",
-			"command": "dotnet test --nologo",
-			"args": [],
-			"problemMatcher": [
-				"$msCompile"
-			],
-			"group": "build"
-		}
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "clean",
+      "type": "shell",
+      "command": "dotnet clean",
+      "problemMatcher": "$msCompile"
+    },
+    {
+      "label": "restore",
+      "type": "shell",
+      "command": "dotnet restore",
+      "problemMatcher": "$msCompile"
+    },
+    {
+      "label": "build",
+      "type": "shell",
+      "command": "dotnet build --nologo",
+      "problemMatcher": "$msCompile",
+      "group": "build"
+    },
+    {
+      "label": "test",
+      "type": "shell",
+      "command": "dotnet test --nologo",
+      "problemMatcher": "$msCompile",
+      "group": "test"
+    },
+    {
+      "label": "ci:validate",
+      "dependsOn": [
+        "clean",
+        "restore",
+        "build",
+        "test"
+      ],
+      "dependsOrder": "sequence",
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    }
+  ]
+}