{"owner":"akkadotnet","repo":"akka.net","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".claude/skills/openspec-apply-change/SKILL.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to Claude Code (claude.ai/code) and other coding agents when\nworking with code in this repository. `CLAUDE.md` is a symlink to this file, so both names\nresolve to the same guidance.\n\n## Build and Test Commands\n\n### Building the Solution\n```bash\n# Standard build\ndotnet build\ndotnet build -c Release\n\n# Build with warnings as errors (CI validation)\ndotnet build -warnaserror\n```\n\n### Running Tests\n```bash\n# Run all tests\ndotnet test -c Release\n\n# Run tests for specific framework\ndotnet test -c Release --framework net8.0\ndotnet test -c Release --framework net48\n\n# Run specific test by name\ndotnet test -c Release --filter DisplayName=\"TestName\"\n\n# Run tests in a specific project\ndotnet test path/to/project.csproj -c Release\n```\n\n### Incremental Testing (for changed code only)\n```bash\n# Run only unit tests for changed projects\ndotnet incrementalist run --config .incrementalist/testsOnly.json -- test -c Release --no-build --framework net8.0\n\n# Run only multi-node tests for changed projects\ndotnet incrementalist run --config .incrementalist/mutliNodeOnly.json -- test -c Release --no-build --framework net8.0\n```\n\n### Code Quality\n```bash\n# Format check\ndotnet format --verify-no-changes\n\n# API compatibility check\ndotnet test -c Release src/core/Akka.API.Tests\n```\n\n### Documentation\n```bash\n# Generate API documentation\ndotnet docfx metadata ./docs/docfx.json --warningsAsErrors\ndotnet docfx build ./docs/docfx.json --warningsAsErrors\n```\n\n### API Approvals\n- Run API approval tests when making public API changes: `dotnet test -c Release src/core/Akka.API.Tests`\n- Approval files live at `src/core/Akka.API.Tests/CoreAPISpec.ApproveCore.approved.txt` (and sibling `*.approved.txt` files)\n- A diff viewer (WinMerge, TortoiseMerge, etc.) makes reviewing/approving API changes easier\n- Follow **extend-only** design — don't modify existing public APIs, only extend them\n- Mark deprecated APIs with `[Obsolete(\"Obsolete since v{current-akka-version}\")]`\n\n## High-Level Architecture\n\n### Project Structure\n- **`/src/core/`** - Core actor framework components\n  - `Akka/` - Base actor system, routing, dispatchers, configuration\n  - `Akka.Remote/` - Distributed actor communication and serialization\n  - `Akka.Cluster/` - Clustering, gossip protocols, distributed coordination\n  - `Akka.Persistence/` - Event sourcing, snapshots, journals\n  - `Akka.Streams/` - Reactive streams with backpressure\n  - `Akka.TestKit/` - Testing utilities for actor systems\n- **`/src/contrib/`** - Contributed modules (DI integrations, serializers, cluster extensions)\n- **`/src/benchmark/`** - Performance benchmarks using BenchmarkDotNet\n- **`/src/examples/`** - Sample applications demonstrating patterns\n- **`/src/**/*.Tests/`** - xUnit test projects\n- **`/docs/`** - Public-facing documentation; contributor policies and style guides live under `docs/community/contributing/`\n\n### Key Architectural Concepts\n- **Actor Model**: Message-driven, hierarchical supervision, location transparency\n- **Fault Tolerance**: Supervision strategies, let-it-crash philosophy\n- **Distribution**: Remote actors, clustering, sharding\n- **Reactive Streams**: Backpressure-aware stream processing\n- **Event Sourcing**: Persistence with journals and snapshots\n\n## Code Style and Conventions\n\n### C# Style\n- Allman style braces (opening brace on new line)\n- 4 spaces indentation, no tabs\n- Private fields prefixed with underscore `_fieldName`; PascalCase for public/protected members\n- Use `var` when the type is apparent\n- No `this.` qualifier unless necessary\n- Sort `using` statements with `System.*` first\n- XML doc comments on public APIs\n- Default to `sealed` classes and records\n- Enable `#nullable enable` in new/modified files\n- Never use `async void`, `.Result`, or `.Wait()` — these cause deadlocks\n- Always pass `CancellationToken` through async call chains\n\n### API Design\n- Maintain compatibility with JVM Akka while being .NET idiomatic\n- Use `Task<T>` instead of Future, `TimeSpan` instead of Duration\n- Extend-only design - don't modify existing public APIs\n- Preserve wire format compatibility for serialization\n- Include unit tests with all changes\n\n### Test Naming\n- Use `DisplayName` attribute for descriptive test names\n- Follow pattern: `Should_ExpectedBehavior_When_Condition`\n\n### General Conventions\n- Keep pull requests small and focused (< 300 lines when possible)\n- Fix warnings instead of suppressing them\n- Treat `TBD` comments as action items to be resolved\n- Benchmark performance-critical changes with BenchmarkDotNet\n- Avoid adding new dependencies without a license/security check\n\n## Akka.NET TestKit Guidelines\n- Actor tests should derive from `AkkaSpec` or `TestKit` to access actor-testing facilities\n- **Always use async TestKit methods** (e.g. `ExpectMsgAsync`, `ExpectNoMsgAsync`, `AwaitAssertAsync`, `FishForMessageAsync`, `ResolveOne`) — never the synchronous variants (`ExpectMsg`, `ExpectNoMsg`, `AwaitAssert`, `.Result`, `.Wait()`)\n- Pass `ITestOutputHelper output` to the test constructor and forward it to the base: `public MySpec(ITestOutputHelper output) : base(config, output)` — this captures all test output, including actor-system logs\n- Configure logging in tests as needed: `akka.loglevel = DEBUG` or `akka.loglevel = INFO`\n- Use `EventFilter` to assert on log messages (e.g. `await EventFilter.Error().ExpectOneAsync(async () => { /* test code */ })`)\n- For dead letters, use `EventFilter.DeadLetter()` (e.g. `await EventFilter.DeadLetter().ExpectAsync(1, async () => { /* code that should dead-letter */ })`)\n- Use `TestProbe` for lightweight test actors to verify interactions\n- Set explicit timeouts on message expectations to avoid long-running tests\n- Tests should clean up after themselves (stop created actors, reset state)\n- Multi-node tests live in separate `*.Tests.MultiNode.csproj` projects\n- To verify specialized message wrappers, check the log form `wrapped in [$TypeName]`\n\n## Development Workflow\n\n### Git Branches\n- **`dev`** - Main development branch (default for PRs)\n- **`v1.4`**, **`v1.3`**, etc. - Version maintenance branches for older releases\n- Feature branches: `feature/description`\n- Bugfix branches: `fix/description`\n\n### Git Repository Management\n- Remotes:\n  - `akkadotnet` / `upstream` → `https://github.com/akkadotnet/akka.net.git` (main repository)\n  - `origin` → your fork (e.g. `https://github.com/yourusername/akka.net.git`)\n- Sync with upstream:\n  - `git fetch akkadotnet` (or `upstream`)\n  - `git checkout dev`\n  - `git merge akkadotnet/dev`\n- Create a feature branch:\n  - `git checkout -b feature/your-feature-name`\n  - `git push -u origin feature/your-feature-name`\n\n### Making Changes\n1. Always read existing code patterns in the module you're modifying\n2. Follow existing conventions for that specific module\n3. Add/update tests for your changes\n4. Run incremental tests before committing\n5. Ensure API compatibility tests pass for core changes\n6. If the change is breaking, record it in `BREAKING_CHANGES_V1.6.md` in the same change (see below)\n\n### Tracking Breaking Changes (v1.6 cycle)\nUntil a stable **v1.6.0** ships, **every** change that goes into the `dev` branch and\nintroduces a **breaking behavior, wire-format, or public-API change** MUST be documented in\n[`BREAKING_CHANGES_V1.6.md`](BREAKING_CHANGES_V1.6.md) (repo root), in the **same PR** that\nmakes the change. Use the entry format described in that file (status, component, type,\nchange, migration). This ledger is retired once `v1.6.0` is released, when its contents are\nfolded into the release notes / upgrade guide.\n\n### Target Frameworks\n- **.NET 8.0** - Primary target\n- **.NET 6.0** - Library compatibility\n- **.NET Framework 4.8** - Legacy support\n- **.NET Standard 2.0** - Library compatibility\n\n## Important Files\n- `Directory.Build.props` - MSBuild properties, package versions\n- `global.json` - .NET SDK version (8.0.403)\n- `xunit.runner.json` - Test configuration (60s timeout, no parallelization)\n- `.incrementalist/*.json` - Incremental build configurations\n- `RELEASE_NOTES.md` - Version history and changelog\n- `BREAKING_CHANGES_V1.6.md` - Running list of v1.6 breaking changes (until v1.6.0 ships)\n",".claude/skills/openspec-apply-change/SKILL.md":"---\nname: openspec-apply-change\ndescription: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n  author: openspec\n  version: \"1.0\"\n  generatedBy: \"1.2.0\"\n---\n\nImplement tasks from an OpenSpec change.\n\n**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.\n\n**Steps**\n\n1. **Select the change**\n\n   If a name is provided, use it. Otherwise:\n   - Infer from conversation context if the user mentioned a change\n   - Auto-select if only one active change exists\n   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select\n\n   Always announce: \"Using change: <name>\" and how to override (e.g., `/opsx:apply <other>`).\n\n2. **Check status to understand the schema**\n   ```bash\n   openspec status --change \"<name>\" --json\n   ```\n   Parse the JSON to understand:\n   - `schemaName`: The workflow being used (e.g., \"spec-driven\")\n   - Which artifact contains the tasks (typically \"tasks\" for spec-driven, check status for others)\n\n3. **Get apply instructions**\n\n   ```bash\n   openspec instructions apply --change \"<name>\" --json\n   ```\n\n   This returns:\n   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)\n   - Progress (total, complete, remaining)\n   - Task list with status\n   - Dynamic instruction based on current state\n\n   **Handle states:**\n   - If `state: \"blocked\"` (missing artifacts): show message, suggest using openspec-continue-change\n   - If `state: \"all_done\"`: congratulate, suggest archive\n   - Otherwise: proceed to implementation\n\n4. **Read context files**\n\n   Read the files listed in `contextFiles` from the apply instructions output.\n   The files depend on the schema being used:\n   - **spec-driven**: proposal, specs, design, tasks\n   - Other schemas: follow the contextFiles from CLI output\n\n5. **Show current progress**\n\n   Display:\n   - Schema being used\n   - Progress: \"N/M tasks complete\"\n   - Remaining tasks overview\n   - Dynamic instruction from CLI\n\n6. **Implement tasks (loop until done or blocked)**\n\n   For each pending task:\n   - Show which task is being worked on\n   - Make the code changes required\n   - Keep changes minimal and focused\n   - Mark task complete in the tasks file: `- [ ]` → `- [x]`\n   - Continue to next task\n\n   **Pause if:**\n   - Task is unclear → ask for clarification\n   - Implementation reveals a design issue → suggest updating artifacts\n   - Error or blocker encountered → report and wait for guidance\n   - User interrupts\n\n7. **On completion or pause, show status**\n\n   Display:\n   - Tasks completed this session\n   - Overall progress: \"N/M tasks complete\"\n   - If all done: suggest archive\n   - If paused: explain why and wait for guidance\n\n**Output During Implementation**\n\n```\n## Implementing: <change-name> (schema: <schema-name>)\n\nWorking on task 3/7: <task description>\n[...implementation happening...]\n✓ Task complete\n\nWorking on task 4/7: <task description>\n[...implementation happening...]\n✓ Task complete\n```\n\n**Output On Completion**\n\n```\n## Implementation Complete\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 7/7 tasks complete ✓\n\n### Completed This Session\n- [x] Task 1\n- [x] Task 2\n...\n\nAll tasks complete! Ready to archive this change.\n```\n\n**Output On Pause (Issue Encountered)**\n\n```\n## Implementation Paused\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 4/7 tasks complete\n\n### Issue Encountered\n<description of the issue>\n\n**Options:**\n1. <option 1>\n2. <option 2>\n3. Other approach\n\nWhat would you like to do?\n```\n\n**Guardrails**\n- Keep going through tasks until done or blocked\n- Always read context files before starting (from the apply instructions output)\n- If task is ambiguous, pause and ask before implementing\n- If implementation reveals issues, pause and suggest artifact updates\n- Keep code changes minimal and scoped to each task\n- Update task checkbox immediately after completing each task\n- Pause on errors, blockers, or unclear requirements - don't guess\n- Use contextFiles from CLI output, don't assume specific file names\n\n**Fluid Workflow Integration**\n\nThis skill supports the \"actions on a change\" model:\n\n- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions\n- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nThis file provides guidance to Claude Code (claude.ai/code) and other coding agents when\nworking with code in this repository. `CLAUDE.md` is a symlink to this file, so both names\nresolve to the same guidance.\n\n## Build and Test Commands\n\n### Building the Solution\n```bash\n# Standard build\ndotnet build\ndotnet build -c Release\n\n# Build with warnings as errors (CI validation)\ndotnet build -warnaserror\n```\n\n### Running Tests\n```bash\n# Run all tests\ndotnet test -c Release\n\n# Run tests for specific framework\ndotnet test -c Release --framework net8.0\ndotnet test -c Release --framework net48\n\n# Run specific test by name\ndotnet test -c Release --filter DisplayName=\"TestName\"\n\n# Run tests in a specific project\ndotnet test path/to/project.csproj -c Release\n```\n\n### Incremental Testing (for changed code only)\n```bash\n# Run only unit tests for changed projects\ndotnet incrementalist run --config .incrementalist/testsOnly.json -- test -c Release --no-build --framework net8.0\n\n# Run only multi-node tests for changed projects\ndotnet incrementalist run --config .incrementalist/mutliNodeOnly.json -- test -c Release --no-build --framework net8.0\n```\n\n### Code Quality\n```bash\n# Format check\ndotnet format --verify-no-changes\n\n# API compatibility check\ndotnet test -c Release src/core/Akka.API.Tests\n```\n\n### Documentation\n```bash\n# Generate API documentation\ndotnet docfx metadata ./docs/docfx.json --warningsAsErrors\ndotnet docfx build ./docs/docfx.json --warningsAsErrors\n```\n\n### API Approvals\n- Run API approval tests when making public API changes: `dotnet test -c Release src/core/Akka.API.Tests`\n- Approval files live at `src/core/Akka.API.Tests/CoreAPISpec.ApproveCore.approved.txt` (and sibling `*.approved.txt` files)\n- A diff viewer (WinMerge, TortoiseMerge, etc.) makes reviewing/approving API changes easier\n- Follow **extend-only** design — don't modify existing public APIs, only extend them\n- Mark deprecated APIs with `[Obsolete(\"Obsolete since v{current-akka-version}\")]`\n\n## High-Level Architecture\n\n### Project Structure\n- **`/src/core/`** - Core actor framework components\n  - `Akka/` - Base actor system, routing, dispatchers, configuration\n  - `Akka.Remote/` - Distributed actor communication and serialization\n  - `Akka.Cluster/` - Clustering, gossip protocols, distributed coordination\n  - `Akka.Persistence/` - Event sourcing, snapshots, journals\n  - `Akka.Streams/` - Reactive streams with backpressure\n  - `Akka.TestKit/` - Testing utilities for actor systems\n- **`/src/contrib/`** - Contributed modules (DI integrations, serializers, cluster extensions)\n- **`/src/benchmark/`** - Performance benchmarks using BenchmarkDotNet\n- **`/src/examples/`** - Sample applications demonstrating patterns\n- **`/src/**/*.Tests/`** - xUnit test projects\n- **`/docs/`** - Public-facing documentation; contributor policies and style guides live under `docs/community/contributing/`\n\n### Key Architectural Concepts\n- **Actor Model**: Message-driven, hierarchical supervision, location transparency\n- **Fault Tolerance**: Supervision strategies, let-it-crash philosophy\n- **Distribution**: Remote actors, clustering, sharding\n- **Reactive Streams**: Backpressure-aware stream processing\n- **Event Sourcing**: Persistence with journals and snapshots\n\n## Code Style and Conventions\n\n### C# Style\n- Allman style braces (opening brace on new line)\n- 4 spaces indentation, no tabs\n- Private fields prefixed with underscore `_fieldName`; PascalCase for public/protected members\n- Use `var` when the type is apparent\n- No `this.` qualifier unless necessary\n- Sort `using` statements with `System.*` first\n- XML doc comments on public APIs\n- Default to `sealed` classes and records\n- Enable `#nullable enable` in new/modified files\n- Never use `async void`, `.Result`, or `.Wait()` — these cause deadlocks\n- Always pass `CancellationToken` through async call chains\n\n### API Design\n- Maintain compatibility with JVM Akka while being .NET idiomatic\n- Use `Task<T>` instead of Future, `TimeSpan` instead of Duration\n- Extend-only design - don't modify existing public APIs\n- Preserve wire format compatibility for serialization\n- Include unit tests with all changes\n\n### Test Naming\n- Use `DisplayName` attribute for descriptive test names\n- Follow pattern: `Should_ExpectedBehavior_When_Condition`\n\n### General Conventions\n- Keep pull requests small and focused (< 300 lines when possible)\n- Fix warnings instead of suppressing them\n- Treat `TBD` comments as action items to be resolved\n- Benchmark performance-critical changes with BenchmarkDotNet\n- Avoid adding new dependencies without a license/security check\n\n## Akka.NET TestKit Guidelines\n- Actor tests should derive from `AkkaSpec` or `TestKit` to access actor-testing facilities\n- **Always use async TestKit methods** (e.g. `ExpectMsgAsync`, `ExpectNoMsgAsync`, `AwaitAssertAsync`, `FishForMessageAsync`, `ResolveOne`) — never the synchronous variants (`ExpectMsg`, `ExpectNoMsg`, `AwaitAssert`, `.Result`, `.Wait()`)\n- Pass `ITestOutputHelper output` to the test constructor and forward it to the base: `public MySpec(ITestOutputHelper output) : base(config, output)` — this captures all test output, including actor-system logs\n- Configure logging in tests as needed: `akka.loglevel = DEBUG` or `akka.loglevel = INFO`\n- Use `EventFilter` to assert on log messages (e.g. `await EventFilter.Error().ExpectOneAsync(async () => { /* test code */ })`)\n- For dead letters, use `EventFilter.DeadLetter()` (e.g. `await EventFilter.DeadLetter().ExpectAsync(1, async () => { /* code that should dead-letter */ })`)\n- Use `TestProbe` for lightweight test actors to verify interactions\n- Set explicit timeouts on message expectations to avoid long-running tests\n- Tests should clean up after themselves (stop created actors, reset state)\n- Multi-node tests live in separate `*.Tests.MultiNode.csproj` projects\n- To verify specialized message wrappers, check the log form `wrapped in [$TypeName]`\n\n## Development Workflow\n\n### Git Branches\n- **`dev`** - Main development branch (default for PRs)\n- **`v1.4`**, **`v1.3`**, etc. - Version maintenance branches for older releases\n- Feature branches: `feature/description`\n- Bugfix branches: `fix/description`\n\n### Git Repository Management\n- Remotes:\n  - `akkadotnet` / `upstream` → `https://github.com/akkadotnet/akka.net.git` (main repository)\n  - `origin` → your fork (e.g. `https://github.com/yourusername/akka.net.git`)\n- Sync with upstream:\n  - `git fetch akkadotnet` (or `upstream`)\n  - `git checkout dev`\n  - `git merge akkadotnet/dev`\n- Create a feature branch:\n  - `git checkout -b feature/your-feature-name`\n  - `git push -u origin feature/your-feature-name`\n\n### Making Changes\n1. Always read existing code patterns in the module you're modifying\n2. Follow existing conventions for that specific module\n3. Add/update tests for your changes\n4. Run incremental tests before committing\n5. Ensure API compatibility tests pass for core changes\n6. If the change is breaking, record it in `BREAKING_CHANGES_V1.6.md` in the same change (see below)\n\n### Tracking Breaking Changes (v1.6 cycle)\nUntil a stable **v1.6.0** ships, **every** change that goes into the `dev` branch and\nintroduces a **breaking behavior, wire-format, or public-API change** MUST be documented in\n[`BREAKING_CHANGES_V1.6.md`](BREAKING_CHANGES_V1.6.md) (repo root), in the **same PR** that\nmakes the change. Use the entry format described in that file (status, component, type,\nchange, migration). This ledger is retired once `v1.6.0` is released, when its contents are\nfolded into the release notes / upgrade guide.\n\n### Target Frameworks\n- **.NET 8.0** - Primary target\n- **.NET 6.0** - Library compatibility\n- **.NET Framework 4.8** - Legacy support\n- **.NET Standard 2.0** - Library compatibility\n\n## Important Files\n- `Directory.Build.props` - MSBuild properties, package versions\n- `global.json` - .NET SDK version (8.0.403)\n- `xunit.runner.json` - Test configuration (60s timeout, no parallelization)\n- `.incrementalist/*.json` - Incremental build configurations\n- `RELEASE_NOTES.md` - Version history and changelog\n- `BREAKING_CHANGES_V1.6.md` - Running list of v1.6 breaking changes (until v1.6.0 ships)\n",".claude/skills/openspec-apply-change/SKILL.md":"---\nname: openspec-apply-change\ndescription: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n  author: openspec\n  version: \"1.0\"\n  generatedBy: \"1.2.0\"\n---\n\nImplement tasks from an OpenSpec change.\n\n**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.\n\n**Steps**\n\n1. **Select the change**\n\n   If a name is provided, use it. Otherwise:\n   - Infer from conversation context if the user mentioned a change\n   - Auto-select if only one active change exists\n   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select\n\n   Always announce: \"Using change: <name>\" and how to override (e.g., `/opsx:apply <other>`).\n\n2. **Check status to understand the schema**\n   ```bash\n   openspec status --change \"<name>\" --json\n   ```\n   Parse the JSON to understand:\n   - `schemaName`: The workflow being used (e.g., \"spec-driven\")\n   - Which artifact contains the tasks (typically \"tasks\" for spec-driven, check status for others)\n\n3. **Get apply instructions**\n\n   ```bash\n   openspec instructions apply --change \"<name>\" --json\n   ```\n\n   This returns:\n   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)\n   - Progress (total, complete, remaining)\n   - Task list with status\n   - Dynamic instruction based on current state\n\n   **Handle states:**\n   - If `state: \"blocked\"` (missing artifacts): show message, suggest using openspec-continue-change\n   - If `state: \"all_done\"`: congratulate, suggest archive\n   - Otherwise: proceed to implementation\n\n4. **Read context files**\n\n   Read the files listed in `contextFiles` from the apply instructions output.\n   The files depend on the schema being used:\n   - **spec-driven**: proposal, specs, design, tasks\n   - Other schemas: follow the contextFiles from CLI output\n\n5. **Show current progress**\n\n   Display:\n   - Schema being used\n   - Progress: \"N/M tasks complete\"\n   - Remaining tasks overview\n   - Dynamic instruction from CLI\n\n6. **Implement tasks (loop until done or blocked)**\n\n   For each pending task:\n   - Show which task is being worked on\n   - Make the code changes required\n   - Keep changes minimal and focused\n   - Mark task complete in the tasks file: `- [ ]` → `- [x]`\n   - Continue to next task\n\n   **Pause if:**\n   - Task is unclear → ask for clarification\n   - Implementation reveals a design issue → suggest updating artifacts\n   - Error or blocker encountered → report and wait for guidance\n   - User interrupts\n\n7. **On completion or pause, show status**\n\n   Display:\n   - Tasks completed this session\n   - Overall progress: \"N/M tasks complete\"\n   - If all done: suggest archive\n   - If paused: explain why and wait for guidance\n\n**Output During Implementation**\n\n```\n## Implementing: <change-name> (schema: <schema-name>)\n\nWorking on task 3/7: <task description>\n[...implementation happening...]\n✓ Task complete\n\nWorking on task 4/7: <task description>\n[...implementation happening...]\n✓ Task complete\n```\n\n**Output On Completion**\n\n```\n## Implementation Complete\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 7/7 tasks complete ✓\n\n### Completed This Session\n- [x] Task 1\n- [x] Task 2\n...\n\nAll tasks complete! Ready to archive this change.\n```\n\n**Output On Pause (Issue Encountered)**\n\n```\n## Implementation Paused\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 4/7 tasks complete\n\n### Issue Encountered\n<description of the issue>\n\n**Options:**\n1. <option 1>\n2. <option 2>\n3. Other approach\n\nWhat would you like to do?\n```\n\n**Guardrails**\n- Keep going through tasks until done or blocked\n- Always read context files before starting (from the apply instructions output)\n- If task is ambiguous, pause and ask before implementing\n- If implementation reveals issues, pause and suggest artifact updates\n- Keep code changes minimal and scoped to each task\n- Update task checkbox immediately after completing each task\n- Pause on errors, blockers, or unclear requirements - don't guess\n- Use contextFiles from CLI output, don't assume specific file names\n\n**Fluid Workflow Integration**\n\nThis skill supports the \"actions on a change\" model:\n\n- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions\n- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nThis file provides guidance to Claude Code (claude.ai/code) and other coding agents when\nworking with code in this repository. `CLAUDE.md` is a symlink to this file, so both names\nresolve to the same guidance.\n\n## Build and Test Commands\n\n### Building the Solution\n```bash\n# Standard build\ndotnet build\ndotnet build -c Release\n\n# Build with warnings as errors (CI validation)\ndotnet build -warnaserror\n```\n\n### Running Tests\n```bash\n# Run all tests\ndotnet test -c Release\n\n# Run tests for specific framework\ndotnet test -c Release --framework net8.0\ndotnet test -c Release --framework net48\n\n# Run specific test by name\ndotnet test -c Release --filter DisplayName=\"TestName\"\n\n# Run tests in a specific project\ndotnet test path/to/project.csproj -c Release\n```\n\n### Incremental Testing (for changed code only)\n```bash\n# Run only unit tests for changed projects\ndotnet incrementalist run --config .incrementalist/testsOnly.json -- test -c Release --no-build --framework net8.0\n\n# Run only multi-node tests for changed projects\ndotnet incrementalist run --config .incrementalist/mutliNodeOnly.json -- test -c Release --no-build --framework net8.0\n```\n\n### Code Quality\n```bash\n# Format check\ndotnet format --verify-no-changes\n\n# API compatibility check\ndotnet test -c Release src/core/Akka.API.Tests\n```\n\n### Documentation\n```bash\n# Generate API documentation\ndotnet docfx metadata ./docs/docfx.json --warningsAsErrors\ndotnet docfx build ./docs/docfx.json --warningsAsErrors\n```\n\n### API Approvals\n- Run API approval tests when making public API changes: `dotnet test -c Release src/core/Akka.API.Tests`\n- Approval files live at `src/core/Akka.API.Tests/CoreAPISpec.ApproveCore.approved.txt` (and sibling `*.approved.txt` files)\n- A diff viewer (WinMerge, TortoiseMerge, etc.) makes reviewing/approving API changes easier\n- Follow **extend-only** design — don't modify existing public APIs, only extend them\n- Mark deprecated APIs with `[Obsolete(\"Obsolete since v{current-akka-version}\")]`\n\n## High-Level Architecture\n\n### Project Structure\n- **`/src/core/`** - Core actor framework components\n  - `Akka/` - Base actor system, routing, dispatchers, configuration\n  - `Akka.Remote/` - Distributed actor communication and serialization\n  - `Akka.Cluster/` - Clustering, gossip protocols, distributed coordination\n  - `Akka.Persistence/` - Event sourcing, snapshots, journals\n  - `Akka.Streams/` - Reactive streams with backpressure\n  - `Akka.TestKit/` - Testing utilities for actor systems\n- **`/src/contrib/`** - Contributed modules (DI integrations, serializers, cluster extensions)\n- **`/src/benchmark/`** - Performance benchmarks using BenchmarkDotNet\n- **`/src/examples/`** - Sample applications demonstrating patterns\n- **`/src/**/*.Tests/`** - xUnit test projects\n- **`/docs/`** - Public-facing documentation; contributor policies and style guides live under `docs/community/contributing/`\n\n### Key Architectural Concepts\n- **Actor Model**: Message-driven, hierarchical supervision, location transparency\n- **Fault Tolerance**: Supervision strategies, let-it-crash philosophy\n- **Distribution**: Remote actors, clustering, sharding\n- **Reactive Streams**: Backpressure-aware stream processing\n- **Event Sourcing**: Persistence with journals and snapshots\n\n## Code Style and Conventions\n\n### C# Style\n- Allman style braces (opening brace on new line)\n- 4 spaces indentation, no tabs\n- Private fields prefixed with underscore `_fieldName`; PascalCase for public/protected members\n- Use `var` when the type is apparent\n- No `this.` qualifier unless necessary\n- Sort `using` statements with `System.*` first\n- XML doc comments on public APIs\n- Default to `sealed` classes and records\n- Enable `#nullable enable` in new/modified files\n- Never use `async void`, `.Result`, or `.Wait()` — these cause deadlocks\n- Always pass `CancellationToken` through async call chains\n\n### API Design\n- Maintain compatibility with JVM Akka while being .NET idiomatic\n- Use `Task<T>` instead of Future, `TimeSpan` instead of Duration\n- Extend-only design - don't modify existing public APIs\n- Preserve wire format compatibility for serialization\n- Include unit tests with all changes\n\n### Test Naming\n- Use `DisplayName` attribute for descriptive test names\n- Follow pattern: `Should_ExpectedBehavior_When_Condition`\n\n### General Conventions\n- Keep pull requests small and focused (< 300 lines when possible)\n- Fix warnings instead of suppressing them\n- Treat `TBD` comments as action items to be resolved\n- Benchmark performance-critical changes with BenchmarkDotNet\n- Avoid adding new dependencies without a license/security check\n\n## Akka.NET TestKit Guidelines\n- Actor tests should derive from `AkkaSpec` or `TestKit` to access actor-testing facilities\n- **Always use async TestKit methods** (e.g. `ExpectMsgAsync`, `ExpectNoMsgAsync`, `AwaitAssertAsync`, `FishForMessageAsync`, `ResolveOne`) — never the synchronous variants (`ExpectMsg`, `ExpectNoMsg`, `AwaitAssert`, `.Result`, `.Wait()`)\n- Pass `ITestOutputHelper output` to the test constructor and forward it to the base: `public MySpec(ITestOutputHelper output) : base(config, output)` — this captures all test output, including actor-system logs\n- Configure logging in tests as needed: `akka.loglevel = DEBUG` or `akka.loglevel = INFO`\n- Use `EventFilter` to assert on log messages (e.g. `await EventFilter.Error().ExpectOneAsync(async () => { /* test code */ })`)\n- For dead letters, use `EventFilter.DeadLetter()` (e.g. `await EventFilter.DeadLetter().ExpectAsync(1, async () => { /* code that should dead-letter */ })`)\n- Use `TestProbe` for lightweight test actors to verify interactions\n- Set explicit timeouts on message expectations to avoid long-running tests\n- Tests should clean up after themselves (stop created actors, reset state)\n- Multi-node tests live in separate `*.Tests.MultiNode.csproj` projects\n- To verify specialized message wrappers, check the log form `wrapped in [$TypeName]`\n\n## Development Workflow\n\n### Git Branches\n- **`dev`** - Main development branch (default for PRs)\n- **`v1.4`**, **`v1.3`**, etc. - Version maintenance branches for older releases\n- Feature branches: `feature/description`\n- Bugfix branches: `fix/description`\n\n### Git Repository Management\n- Remotes:\n  - `akkadotnet` / `upstream` → `https://github.com/akkadotnet/akka.net.git` (main repository)\n  - `origin` → your fork (e.g. `https://github.com/yourusername/akka.net.git`)\n- Sync with upstream:\n  - `git fetch akkadotnet` (or `upstream`)\n  - `git checkout dev`\n  - `git merge akkadotnet/dev`\n- Create a feature branch:\n  - `git checkout -b feature/your-feature-name`\n  - `git push -u origin feature/your-feature-name`\n\n### Making Changes\n1. Always read existing code patterns in the module you're modifying\n2. Follow existing conventions for that specific module\n3. Add/update tests for your changes\n4. Run incremental tests before committing\n5. Ensure API compatibility tests pass for core changes\n6. If the change is breaking, record it in `BREAKING_CHANGES_V1.6.md` in the same change (see below)\n\n### Tracking Breaking Changes (v1.6 cycle)\nUntil a stable **v1.6.0** ships, **every** change that goes into the `dev` branch and\nintroduces a **breaking behavior, wire-format, or public-API change** MUST be documented in\n[`BREAKING_CHANGES_V1.6.md`](BREAKING_CHANGES_V1.6.md) (repo root), in the **same PR** that\nmakes the change. Use the entry format described in that file (status, component, type,\nchange, migration). This ledger is retired once `v1.6.0` is released, when its contents are\nfolded into the release notes / upgrade guide.\n\n### Target Frameworks\n- **.NET 8.0** - Primary target\n- **.NET 6.0** - Library compatibility\n- **.NET Framework 4.8** - Legacy support\n- **.NET Standard 2.0** - Library compatibility\n\n## Important Files\n- `Directory.Build.props` - MSBuild properties, package versions\n- `global.json` - .NET SDK version (8.0.403)\n- `xunit.runner.json` - Test configuration (60s timeout, no parallelization)\n- `.incrementalist/*.json` - Incremental build configurations\n- `RELEASE_NOTES.md` - Version history and changelog\n- `BREAKING_CHANGES_V1.6.md` - Running list of v1.6 breaking changes (until v1.6.0 ships)\n","category":"root","tokens":2050},{"name":"SKILL.md","path":".claude/skills/openspec-apply-change/SKILL.md","title":"openspec-apply-change Skill","content":"---\nname: openspec-apply-change\ndescription: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.\nlicense: MIT\ncompatibility: Requires openspec CLI.\nmetadata:\n  author: openspec\n  version: \"1.0\"\n  generatedBy: \"1.2.0\"\n---\n\nImplement tasks from an OpenSpec change.\n\n**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.\n\n**Steps**\n\n1. **Select the change**\n\n   If a name is provided, use it. Otherwise:\n   - Infer from conversation context if the user mentioned a change\n   - Auto-select if only one active change exists\n   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select\n\n   Always announce: \"Using change: <name>\" and how to override (e.g., `/opsx:apply <other>`).\n\n2. **Check status to understand the schema**\n   ```bash\n   openspec status --change \"<name>\" --json\n   ```\n   Parse the JSON to understand:\n   - `schemaName`: The workflow being used (e.g., \"spec-driven\")\n   - Which artifact contains the tasks (typically \"tasks\" for spec-driven, check status for others)\n\n3. **Get apply instructions**\n\n   ```bash\n   openspec instructions apply --change \"<name>\" --json\n   ```\n\n   This returns:\n   - Context file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)\n   - Progress (total, complete, remaining)\n   - Task list with status\n   - Dynamic instruction based on current state\n\n   **Handle states:**\n   - If `state: \"blocked\"` (missing artifacts): show message, suggest using openspec-continue-change\n   - If `state: \"all_done\"`: congratulate, suggest archive\n   - Otherwise: proceed to implementation\n\n4. **Read context files**\n\n   Read the files listed in `contextFiles` from the apply instructions output.\n   The files depend on the schema being used:\n   - **spec-driven**: proposal, specs, design, tasks\n   - Other schemas: follow the contextFiles from CLI output\n\n5. **Show current progress**\n\n   Display:\n   - Schema being used\n   - Progress: \"N/M tasks complete\"\n   - Remaining tasks overview\n   - Dynamic instruction from CLI\n\n6. **Implement tasks (loop until done or blocked)**\n\n   For each pending task:\n   - Show which task is being worked on\n   - Make the code changes required\n   - Keep changes minimal and focused\n   - Mark task complete in the tasks file: `- [ ]` → `- [x]`\n   - Continue to next task\n\n   **Pause if:**\n   - Task is unclear → ask for clarification\n   - Implementation reveals a design issue → suggest updating artifacts\n   - Error or blocker encountered → report and wait for guidance\n   - User interrupts\n\n7. **On completion or pause, show status**\n\n   Display:\n   - Tasks completed this session\n   - Overall progress: \"N/M tasks complete\"\n   - If all done: suggest archive\n   - If paused: explain why and wait for guidance\n\n**Output During Implementation**\n\n```\n## Implementing: <change-name> (schema: <schema-name>)\n\nWorking on task 3/7: <task description>\n[...implementation happening...]\n✓ Task complete\n\nWorking on task 4/7: <task description>\n[...implementation happening...]\n✓ Task complete\n```\n\n**Output On Completion**\n\n```\n## Implementation Complete\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 7/7 tasks complete ✓\n\n### Completed This Session\n- [x] Task 1\n- [x] Task 2\n...\n\nAll tasks complete! Ready to archive this change.\n```\n\n**Output On Pause (Issue Encountered)**\n\n```\n## Implementation Paused\n\n**Change:** <change-name>\n**Schema:** <schema-name>\n**Progress:** 4/7 tasks complete\n\n### Issue Encountered\n<description of the issue>\n\n**Options:**\n1. <option 1>\n2. <option 2>\n3. Other approach\n\nWhat would you like to do?\n```\n\n**Guardrails**\n- Keep going through tasks until done or blocked\n- Always read context files before starting (from the apply instructions output)\n- If task is ambiguous, pause and ask before implementing\n- If implementation reveals issues, pause and suggest artifact updates\n- Keep code changes minimal and scoped to each task\n- Update task checkbox immediately after completing each task\n- Pause on errors, blockers, or unclear requirements - don't guess\n- Use contextFiles from CLI output, don't assume specific file names\n\n**Fluid Workflow Integration**\n\nThis skill supports the \"actions on a change\" model:\n\n- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions\n- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly\n","category":".claude","tokens":1178}]}