Agent instructions

[adamhathcock]

This pull request adds a new documentation file, .github/copilot-instructions.md, which provides comprehensive instructions and guidelines for AI agents (and developers) working on the SharpCompress project. The document covers project architecture, API design patterns, development workflow, code conventions, testing strategies, format-specific knowledge, and common pitfalls, serving as an in-depth onboarding and reference guide.

Key additions in the new documentation:

Project Architecture and API Design:

• Explains the three-tier API structure (Archive, Reader, Writer), the factory pattern for format detection, and stream disposal rules, including recent changes and best practices.

Development Workflow and Code Conventions:

• Details build, test, and formatting commands, VS Code tasks, debugging features, and enforces code style rules such as nullable reference types, async/await patterns, and naming conventions.

Testing and Format-Specific Guidance:

• Outlines testing patterns, organization, and critical test areas; provides format-specific notes for Tar, Zip, Rar, and 7Zip, including limitations and edge cases.

Project Structure and Common Pitfalls:

• Describes the directory structure and highlights common mistakes to avoid when working with the codebase, such as API misuse and stream handling errors.

Performance Tips and References:

• Offers performance considerations and

[adamhathcock]

@copilot see if this needs to be consolidated with other files in the .github directory and AGENTS.md

[Copilot]

@adamhathcock I've opened a new pull request, #1058, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

This pull request adds a comprehensive AI agent instruction document (.github/copilot-instructions.md) that consolidates development guidelines, architecture patterns, and coding conventions for the SharpCompress project. The document serves as an onboarding and reference guide covering API design, development workflows, testing patterns, and format-specific knowledge.

Key changes:

• New 204-line documentation file providing structured guidance on project architecture, API patterns, code conventions, and testing strategies
• Covers three-tier API design (Archive/Reader/Writer), factory patterns, stream disposal rules, and format-specific considerations for Tar, Zip, Rar, and 7Zip
• Includes practical examples, common pitfalls, build/test commands, and references to existing documentation files

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation states that DEBUG_STREAMS is "enabled for net10.0 Debug builds", but according to the project file, it's actually enabled for both net8.0 and net10.0 Debug builds. This should be updated to include both target frameworks.

Suggested change

	When building with `DEBUG_STREAMS` constant (enabled for net10.0 Debug builds):
	When building with `DEBUG_STREAMS` constant (enabled for net8.0 and net10.0 Debug builds):

[Copilot]

The document states that SharpCompress targets ".NET Framework 4.8, .NET 8.0, and .NET 10.0", but according to the project file (SharpCompress.csproj), the actual targets are net48, net8.0, and net10.0. While this is technically correct for .NET 10.0, it's inconsistent with the existing AGENTS.md file which lists ".NET Framework 4.62, .NET Standard 2.1, .NET 6.0, and .NET 8.0". The project should be checked to confirm the actual target frameworks, as the documentation appears to have outdated or incorrect information.

Suggested change

	SharpCompress is a pure C# compression library supporting multiple archive formats (Zip, Tar, GZip, BZip2, 7Zip, Rar, LZip, XZ, ZStandard) for .NET Framework 4.8, .NET 8.0, and .NET 10.0. The library provides both seekable Archive APIs and forward-only Reader/Writer APIs for streaming scenarios.
	SharpCompress is a pure C# compression library supporting multiple archive formats (Zip, Tar, GZip, BZip2, 7Zip, Rar, LZip, XZ, ZStandard) targeting .NET Framework 4.8 (`net48`), .NET 8.0 (`net8.0`), and .NET 10.0 (`net10.0`). The library provides both seekable Archive APIs and forward-only Reader/Writer APIs for streaming scenarios.

[Copilot]

The comment states that the library targets include "net481", but the actual project file shows the targets are "net48;net8.0;net10.0" (no net481). This is incorrect and should be updated to match the actual TargetFrameworks in SharpCompress.csproj.

Suggested change

	# Build specific framework (library targets: net48, net481, netstandard2.0, net6.0, net8.0)
	# Build specific framework (library targets: net48, net8.0, net10.0)

[Copilot]

The document states "Use latest C# features (currently C# 14)" but the existing AGENTS.md file indicates "currently C# 13 features" (line 12). C# 14 has not been released as of the knowledge cutoff (January 2025). This appears to be speculative or incorrect information about the C# version.

Suggested change

	- Use latest C# features (currently C# 14)
	- Use latest C# features (currently C# 13)

[Copilot]

The documentation references NonDisposingStream wrapper with "(if it exists)" suggesting uncertainty. A search of the codebase shows this class does not exist in the SharpCompress source code. This reference should either be removed or corrected to reflect the actual stream wrapper utilities available in the project.

Suggested change

	- When working with compression streams directly, use `NonDisposingStream` wrapper (if it exists)
	- When working with compression streams directly, always use the `LeaveStreamOpen = true` option to prevent the underlying stream from being disposed.