add some markdown files for planning

.github/COPILOT_AGENT_README.md

@@ -1,15 +0,0 @@
-# Copilot Coding Agent Configuration
-
-This repository includes a minimal opt-in configuration and CI workflow to allow the GitHub Copilot coding agent to open and validate PRs.
-
-- .copilot-agent.yml: opt-in config for automated agents
-- .github/agents/copilot-agent.yml: detailed agent policy configuration
-- .github/workflows/dotnetcore.yml: CI runs on PRs touching the solution, source, or tests to validate changes
-- AGENTS.md: general instructions for Copilot coding agent with project-specific guidelines
-
-Maintainers can adjust the allowed paths or disable the agent by editing or removing .copilot-agent.yml.
-
-Notes:
-- The agent can create, modify, and delete files within the allowed paths (src, tests, README.md, AGENTS.md)
-- All changes require review before merge
-- If build/test paths are different, update the workflow accordingly; this workflow targets SharpCompress.sln and the SharpCompress.Test test project.

.github/prompts/plan-async.prompt.md

@@ -0,0 +1,25 @@
+# Plan: Implement Missing Async Functionality in SharpCompress
+
+SharpCompress has async support for low-level stream operations and Reader/Writer APIs, but critical entry points (Archive.Open, factory methods, initialization) remain synchronous. This plan adds async overloads for all user-facing I/O operations and fixes existing async bugs, enabling full end-to-end async workflows.
+
+## Steps
+
+1. **Add async factory methods** to [ArchiveFactory.cs](src/SharpCompress/Factories/ArchiveFactory.cs), [ReaderFactory.cs](src/SharpCompress/Factories/ReaderFactory.cs), and [WriterFactory.cs](src/SharpCompress/Factories/WriterFactory.cs) with `OpenAsync` and `CreateAsync` overloads accepting `CancellationToken`
+
+2. **Implement async Open methods** on concrete archive types ([ZipArchive.cs](src/SharpCompress/Archives/Zip/ZipArchive.cs), [TarArchive.cs](src/SharpCompress/Archives/Tar/TarArchive.cs), [RarArchive.cs](src/SharpCompress/Archives/Rar/RarArchive.cs), [GZipArchive.cs](src/SharpCompress/Archives/GZip/GZipArchive.cs), [SevenZipArchive.cs](src/SharpCompress/Archives/SevenZip/SevenZipArchive.cs)) and reader types ([ZipReader.cs](src/SharpCompress/Readers/Zip/ZipReader.cs), [TarReader.cs](src/SharpCompress/Readers/Tar/TarReader.cs), etc.)
+
+3. **Convert archive initialization logic to async** including header reading, volume loading, and format signature detection across archive constructors and internal initialization methods
+
+4. **Fix LZMA decoder async bugs** in [LzmaStream.cs](src/SharpCompress/Compressors/LZMA/LzmaStream.cs), [Decoder.cs](src/SharpCompress/Compressors/LZMA/Decoder.cs), and [OutWindow.cs](src/SharpCompress/Compressors/LZMA/OutWindow.cs) to enable true async 7Zip support and remove `NonDisposingStream` workaround
+
+5. **Complete Rar async implementation** by converting `UnpackV2017` methods to async in [UnpackV2017.cs](src/SharpCompress/Compressors/Rar/UnpackV2017.cs) and updating Rar20 decompression
+
+6. **Add comprehensive async tests** covering all new async entry points, cancellation scenarios, and concurrent operations across all archive formats in test files
+
+## Further Considerations
+
+1. **Breaking changes** - Should new async methods be added alongside existing sync methods (non-breaking), or should sync methods eventually be deprecated? Recommend additive approach for backward compatibility.
+
+2. **Performance impact** - Header parsing for formats like Zip/Tar is often small; consider whether truly async parsing adds value vs sync parsing wrapped in Task, or make it conditional based on stream type (network vs file).
+
+3. **7Zip complexity** - The LZMA async bug fix (Step 4) may be challenging due to state management in the decoder; consider whether to scope it separately or implement a simpler workaround that maintains correctness.

.github/prompts/plan-for-next.prompt.md

@@ -0,0 +1,123 @@
+# Plan: Modernize SharpCompress Public API
+
+Based on comprehensive analysis, the API has several inconsistencies around factory patterns, async support, format capabilities, and options classes. Most improvements can be done incrementally without breaking changes.
+
+## Steps
+
+1. **Standardize factory patterns** by deprecating format-specific static `Open` methods in [Archives/Zip/ZipArchive.cs](src/SharpCompress/Archives/Zip/ZipArchive.cs), [Archives/Tar/TarArchive.cs](src/SharpCompress/Archives/Tar/TarArchive.cs), etc. in favor of centralized [Factories/ArchiveFactory.cs](src/SharpCompress/Factories/ArchiveFactory.cs)
+
+2. **Complete async implementation** in [Writers/Zip/ZipWriter.cs](src/SharpCompress/Writers/Zip/ZipWriter.cs) and other writers that currently use sync-over-async, implementing true async I/O throughout the writer hierarchy
+
+3. **Unify options classes** by making [Common/ExtractionOptions.cs](src/SharpCompress/Common/ExtractionOptions.cs) inherit from `OptionsBase` and adding progress reporting to extraction methods consistently
+
+4. **Clarify GZip semantics** in [Archives/GZip/GZipArchive.cs](src/SharpCompress/Archives/GZip/GZipArchive.cs) by adding XML documentation explaining single-entry limitation and relationship to GZip compression used in Tar.gz
+
+## Further Considerations
+
+1. **Breaking changes roadmap** - Should we plan a major version (2.0) to remove deprecated factory methods, clean up `ArchiveType` enum (remove Arc/Arj or add full support), and consolidate naming patterns?
+
+2. **Progress reporting consistency** - Should `IProgress<ArchiveExtractionProgress<IEntry>>` be added to all extraction extension methods or consolidated into options classes?
+
+## Detailed Analysis
+
+### Factory Pattern Issues
+
+Three different factory patterns exist with overlapping functionality:
+
+1. **Static Factories**: ArchiveFactory, ReaderFactory, WriterFactory
+2. **Instance Factories**: IArchiveFactory, IReaderFactory, IWriterFactory
+3. **Format-specific static methods**: Each archive class has static `Open` methods
+
+**Example confusion:**
+```csharp
+// Three ways to open a Zip archive - which is recommended?
+var archive1 = ArchiveFactory.Open("file.zip");
+var archive2 = ZipArchive.Open("file.zip");
+var archive3 = ArchiveFactory.AutoFactory.Open(fileInfo, options);
+```
+
+### Async Support Gaps
+
+Base `IWriter` interface has async methods, but writer implementations provide minimal async support. Most writers just call synchronous methods:
+
+```csharp
+public virtual async Task WriteAsync(...)
+{
+    // Default implementation calls synchronous version
+    Write(filename, source, modificationTime);
+    await Task.CompletedTask.ConfigureAwait(false);
+}
+```
+
+Real async implementations only in:
+- `TarWriter` - Proper async implementation
+- Most other writers use sync-over-async
+
+### GZip Archive Special Case
+
+GZip is treated as both a compression format and an archive format, but only supports single-entry archives:
+
+```csharp
+protected override GZipArchiveEntry CreateEntryInternal(...)
+{
+    if (Entries.Any())
+    {
+        throw new InvalidFormatException("Only one entry is allowed in a GZip Archive");
+    }
+    // ...
+}
+```
+
+### Options Class Hierarchy
+
+```
+OptionsBase (LeaveStreamOpen, ArchiveEncoding)
+  ├─ ReaderOptions (LookForHeader, Password, DisableCheckIncomplete, BufferSize, ExtensionHint, Progress)
+  ├─ WriterOptions (CompressionType, CompressionLevel, Progress)
+  │   ├─ ZipWriterOptions (ArchiveComment, UseZip64)
+  │   ├─ TarWriterOptions (FinalizeArchiveOnClose, HeaderFormat)
+  │   └─ GZipWriterOptions (no additional properties)
+  └─ ExtractionOptions (standalone - Overwrite, ExtractFullPath, PreserveFileTime, PreserveAttributes)
+```
+
+**Issues:**
+- `ExtractionOptions` doesn't inherit from `OptionsBase` - no encoding support during extraction
+- Progress reporting inconsistency between readers and extraction
+- Obsolete properties (`ChecksumIsValid`, `Version`) with unclear migration path
+
+### Implementation Priorities
+
+**High Priority (Non-Breaking):**
+1. Add API usage guide (Archive vs Reader, factory recommendations, async best practices)
+2. Fix progress reporting consistency
+3. Complete async implementation in writers
+
+**Medium Priority (Next Major Version):**
+1. Unify factory pattern - deprecate format-specific static `Open` methods
+2. Clean up options classes - make `ExtractionOptions` inherit from `OptionsBase`
+3. Clarify archive types - remove Arc/Arj from `ArchiveType` enum or add full support
+4. Standardize naming across archive types
+
+**Low Priority:**
+1. Add BZip2 archive support similar to GZipArchive
+2. Complete obsolete property cleanup with migration guide
+
+### Backward Compatibility Strategy
+
+**Safe (Non-Breaking) Changes:**
+- Add new methods to interfaces (use default implementations)
+- Add new options properties (with defaults)
+- Add new factory methods
+- Improve async implementations
+- Add progress reporting support
+
+**Breaking Changes to Avoid:**
+- ❌ Removing format-specific `Open` methods (deprecate instead)
+- ❌ Changing `LeaveStreamOpen` default (currently `true`)
+- ❌ Removing obsolete properties before major version bump
+- ❌ Changing return types or signatures of existing methods
+
+**Deprecation Pattern:**
+- Use `[Obsolete]` for one major version
+- Use `[EditorBrowsable(EditorBrowsableState.Never)]` in next major version
+- Remove in following major version