diff --git a/PROJECT_IMPROVEMENTS.md b/PROJECT_IMPROVEMENTS.md
new file mode 100644
index 0000000..d950adf
--- /dev/null
+++ b/PROJECT_IMPROVEMENTS.md
@@ -0,0 +1,615 @@
+# TestFrameworkBoilerplate - Project Improvements Review
+
+**Date:** 2025-11-28
+**Reviewer:** Claude Code
+**Branch:** claude/review-project-improvements-01F6NoDFRWnvgdTmJNXzyhjQ
+
+---
+
+## Executive Summary
+
+This review identifies opportunities to enhance code quality, security, documentation, and developer experience for the TestFrameworkBoilerplate project. The project is well-structured with solid foundations, but several improvements can make it more robust, maintainable, and production-ready.
+
+---
+
+## 🔴 Critical Issues (Fix Immediately)
+
+### 1. Broken Assertions in Test Steps
+**Location:** `TestFrameworkBoilerplate.Tests.Integration/Steps/HttpExamplesSteps.cs`
+
+**Issues:**
+- Line 31: `response.StatusCode.Equals(Int32.Parse(statusCode));` - Result not used
+- Line 43: `response.StatusCode.Equals(StatusCodes.Status201Created);` - Result not used
+
+**Impact:** Tests pass even when status codes don't match expected values
+
+**Fix:**
+```csharp
+// Line 31 - Replace with assertion
+response.StatusCode.ShouldBe((HttpStatusCode)Int32.Parse(statusCode));
+
+// Line 43 - Replace with assertion
+response.StatusCode.ShouldBe(HttpStatusCode.Created);
+```
+
+### 2. Duplicate Project Reference
+**Location:** `TestFrameworkBoilerplate.Tests.Integration/TestFrameworkBoilerplate.Tests.Integration.csproj`
+
+**Issue:** Lines 30 and 34 contain identical WireMock project references
+
+**Fix:** Remove one of the duplicate references
+
+### 3. Unused Variable
+**Location:** `TestFrameworkBoilerplate.Tests.Integration/Drivers/RestSharpDriver.cs:26`
+
+**Issue:** `var a = _wireMockDriver.GetUrl();` - Debug code left in production
+
+**Fix:** Remove the unused variable
+
+---
+
+## 🟠 High Priority (Address Soon)
+
+### 4. Documentation Gaps
+
+**README.md Missing Sections:**
+- "How to start" - TBA
+- "Project structure" - TBA
+- "Configuration" - TBA
+
+**Recommendations:**
+```markdown
+## How to start
+
+### As a Template User
+1. Install the template: `dotnet new install TestFrameworkBoilerplate.Template`
+2. Create new project: `dotnet new testfw -n MyTests`
+3. Or use interactive setup: `pwsh setup.ps1`
+
+### As a Contributor
+1. Clone repository: `git clone https://github.com/fszymaniak/TestFrameworkBoilerplate.git`
+2. Restore dependencies: `dotnet restore`
+3. Build: `dotnet build`
+4. Run tests: `dotnet test`
+
+## Project structure
+```
+TestFrameworkBoilerplate/
+├── .github/workflows/      # CI/CD pipelines
+├── .template.config/       # Template configuration
+├── TestFrameworkBoilerplate.Tests.Integration/  # Main test project
+│   ├── Configuration/      # Settings classes
+│   ├── Drivers/           # Driver pattern implementation
+│   ├── Features/          # SpecFlow Gherkin scenarios
+│   ├── Steps/             # Step definitions
+│   └── Support/           # DI setup
+└── TestFrameworkBoilerplate.Tests.WireMock/    # HTTP mocking library
+```
+
+## Configuration
+See [appsettings.json](TestFrameworkBoilerplate.Tests.Integration/appsettings.json) for runtime configuration.
+
+Template parameters: See [TEMPLATE_USAGE.md](TEMPLATE_USAGE.md#template-parameters-reference)
+```
+
+### 5. Enable Nullable Reference Types
+
+**Location:** `TestFrameworkBoilerplate.Tests.Integration.csproj:6`
+
+**Current:** `<Nullable>disable</Nullable>`
+
+**Issue:** Missing compile-time null safety checks
+
+**Recommendation:**
+```xml
+<Nullable>enable</Nullable>
+```
+
+**Note:** Will require code updates to handle nullability warnings
+
+### 6. Missing Security Policy
+
+**Issue:** No SECURITY.md file for vulnerability reporting
+
+**Recommendation:** Create `SECURITY.md`:
+```markdown
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it via:
+- **Email:** [your-email@example.com]
+- **Private Security Advisory:** https://github.com/fszymaniak/TestFrameworkBoilerplate/security/advisories/new
+
+**Do not** create public GitHub issues for security vulnerabilities.
+
+We will respond within 48 hours with next steps.
+```
+
+### 7. Code Quality Job Should Fail on Vulnerabilities
+
+**Location:** `.github/workflows/dotnet.yml:114-118`
+
+**Current:** Only warns about vulnerabilities
+
+**Recommendation:**
+```yaml
+- name: Check for security vulnerabilities
+  run: |
+    dotnet list package --vulnerable --include-transitive 2>&1 | tee vulnerabilities.txt
+    if grep -q "has the following vulnerable packages" vulnerabilities.txt; then
+      echo "::error::Security vulnerabilities detected. Review vulnerabilities.txt"
+      exit 1  # Fail the build
+    fi
+```
+
+---
+
+## 🟡 Medium Priority (Plan for Next Sprint)
+
+### 8. Missing Async Best Practices
+
+**Issue:** Async methods don't use `ConfigureAwait(false)` or cancellation tokens
+
+**Recommendation:** Add cancellation token support:
+```csharp
+public async Task<RestResponse> GetAsync(string endpoint, CancellationToken cancellationToken = default)
+{
+    var request = new RestRequest(endpoint);
+    var response = await _client.ExecuteAsync(request, cancellationToken).ConfigureAwait(false);
+    return response;
+}
+```
+
+### 9. No Timeout Configuration for RestClient
+
+**Location:** `RestSharpDriver.cs:18`
+
+**Issue:** RestClient created without timeout configuration
+
+**Recommendation:**
+```csharp
+_client = new RestClient(new RestClientOptions(_wireMockDriver.GetUrl())
+{
+    Timeout = TimeSpan.FromSeconds(30),
+    MaxTimeout = TimeSpan.FromMinutes(2)
+});
+```
+
+### 10. Missing HTTP Methods
+
+**Current:** Only GET, POST, PUT implemented
+
+**Recommendation:** Add DELETE and PATCH methods:
+```csharp
+public async Task<RestResponse> DeleteAsync(string endpoint)
+{
+    var request = new RestRequest(endpoint, Method.Delete);
+    return await _client.ExecuteAsync(request);
+}
+
+public async Task<RestResponse> PatchAsync(string endpoint, string requestBody)
+{
+    var request = new RestRequest(endpoint, Method.Patch);
+    request.AddHeader(ResponseConstants.Header.ContentType, ResponseConstants.Header.ApplicationType);
+    request.AddBody(requestBody);
+    return await _client.ExecuteAsync(request);
+}
+```
+
+### 11. Missing EditorConfig
+
+**Issue:** No consistent code style configuration
+
+**Recommendation:** Create `.editorconfig`:
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.cs]
+indent_style = space
+indent_size = 4
+
+# C# Code Style Rules
+csharp_prefer_braces = true:warning
+csharp_prefer_simple_using_statement = true:suggestion
+csharp_style_namespace_declarations = file_scoped:warning
+
+# .NET Code Quality Rules
+dotnet_code_quality_unused_parameters = all:warning
+dotnet_diagnostic.CA1031.severity = warning
+
+[*.json]
+indent_size = 2
+
+[*.yml]
+indent_size = 2
+```
+
+### 12. Missing Dependabot Configuration
+
+**Issue:** No automated dependency updates
+
+**Recommendation:** Create `.github/dependabot.yml`:
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "nuget"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "nuget"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+```
+
+### 13. Add CodeQL Security Scanning
+
+**Recommendation:** Add to `.github/workflows/dotnet.yml`:
+```yaml
+codeql-analysis:
+  runs-on: ubuntu-latest
+  permissions:
+    security-events: write
+    actions: read
+    contents: read
+
+  steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: csharp
+
+    - name: Setup .NET
+      uses: actions/setup-dotnet@v4
+      with:
+        dotnet-version: '8.0.x'
+
+    - name: Build
+      run: dotnet build --configuration Release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+```
+
+### 14. Missing Code Coverage Reporting
+
+**Issue:** Coverage collected but not reported
+
+**Recommendation:** Add Codecov integration:
+```yaml
+- name: Upload coverage to Codecov
+  if: matrix.os == 'ubuntu-latest'
+  uses: codecov/codecov-action@v4
+  with:
+    files: TestResults/**/coverage.cobertura.xml
+    fail_ci_if_error: true
+    flags: unittests
+    name: codecov-umbrella
+```
+
+---
+
+## 🟢 Low Priority (Nice to Have)
+
+### 15. Missing Contribution Guidelines
+
+**Recommendation:** Create `CONTRIBUTING.md`:
+```markdown
+# Contributing to TestFrameworkBoilerplate
+
+## How to Contribute
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run tests: `dotnet test`
+5. Commit with descriptive message: `git commit -m "Add feature: description"`
+6. Push to your fork: `git push origin feature/your-feature`
+7. Open a Pull Request
+
+## Code Standards
+
+- Follow existing code style
+- Add tests for new features
+- Update documentation
+- Ensure CI/CD passes
+
+## Testing Template Changes
+
+1. Install locally: `dotnet new install .`
+2. Create test project: `dotnet new testfw -n TestProject`
+3. Verify it builds and tests pass
+
+See [TEMPLATE_USAGE.md](TEMPLATE_USAGE.md) for more details.
+```
+
+### 16. Add NuGet Package Icon
+
+**Location:** `TestFrameworkBoilerplate.Template.nuspec`
+
+**Recommendation:** Add icon for better visibility:
+```xml
+<metadata>
+  ...
+  <icon>icon.png</icon>
+  ...
+</metadata>
+<files>
+  <file src="icon.png" target="" />
+  ...
+</files>
+```
+
+### 17. Missing .gitattributes
+
+**Recommendation:** Create `.gitattributes` for consistent line endings:
+```
+* text=auto eol=lf
+
+*.cs text diff=csharp
+*.sln text eol=crlf
+*.csproj text
+*.json text
+*.md text
+*.yml text
+
+*.png binary
+*.jpg binary
+*.nupkg binary
+```
+
+### 18. Add Issue Templates
+
+**Recommendation:** Create `.github/ISSUE_TEMPLATE/bug_report.yml`:
+```yaml
+name: Bug Report
+description: Report a bug in TestFrameworkBoilerplate
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Clear description of the bug
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: How to reproduce the issue
+      placeholder: |
+        1. Create project with `dotnet new testfw -n MyTests`
+        2. Run `dotnet build`
+        3. See error
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Template Version
+      description: Which version of the template?
+    validations:
+      required: true
+
+  - type: input
+    id: dotnet-version
+    attributes:
+      label: .NET Version
+      description: Output of `dotnet --version`
+    validations:
+      required: true
+```
+
+### 19. Add Pull Request Template
+
+**Recommendation:** Create `.github/pull_request_template.md`:
+```markdown
+## Description
+<!-- Describe your changes -->
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Template improvement
+
+## Checklist
+- [ ] Code follows project style
+- [ ] Self-review completed
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] Template tested locally
+- [ ] CI/CD passes
+```
+
+### 20. Add Retry Policy for HTTP Calls
+
+**Recommendation:** Use Polly for resilience:
+```csharp
+// Add to .csproj
+<PackageReference Include="Polly" Version="8.4.2" />
+
+// In RestSharpDriver
+private readonly AsyncRetryPolicy<RestResponse> _retryPolicy;
+
+public RestSharpDriver(...)
+{
+    _retryPolicy = Policy
+        .HandleResult<RestResponse>(r => !r.IsSuccessful && (int)r.StatusCode >= 500)
+        .WaitAndRetryAsync(3, retryAttempt =>
+            TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
+}
+
+public async Task<RestResponse> GetAsync(string endpoint)
+{
+    return await _retryPolicy.ExecuteAsync(async () =>
+    {
+        var request = new RestRequest(endpoint);
+        return await _client.ExecuteAsync(request);
+    });
+}
+```
+
+### 21. Add Logging Support
+
+**Recommendation:** Add structured logging:
+```csharp
+// Add to .csproj
+<PackageReference Include="Serilog" Version="4.1.0" />
+<PackageReference Include="Serilog.Extensions.Logging" Version="8.0.0" />
+<PackageReference Include="Serilog.Sinks.Console" Version="6.0.0" />
+
+// In RestSharpDriver
+private readonly ILogger<RestSharpDriver> _logger;
+
+public async Task<RestResponse> GetAsync(string endpoint)
+{
+    _logger.LogInformation("Executing GET request to {Endpoint}", endpoint);
+    var request = new RestRequest(endpoint);
+    var response = await _client.ExecuteAsync(request);
+    _logger.LogInformation("GET request completed with status {StatusCode}", response.StatusCode);
+    return response;
+}
+```
+
+### 22. Add CODEOWNERS File
+
+**Recommendation:** Create `.github/CODEOWNERS`:
+```
+# Default owner for everything
+* @fszymaniak
+
+# Template configuration
+/.template.config/ @fszymaniak
+
+# CI/CD workflows
+/.github/workflows/ @fszymaniak
+
+# Documentation
+*.md @fszymaniak
+```
+
+---
+
+## 📊 Metrics & Recommendations
+
+### Current State
+- **Total C# Files:** 24
+- **Test Projects:** 2
+- **CI/CD Matrix:** 3 OS (Ubuntu, Windows, macOS)
+- **Target Framework:** .NET 8.0
+- **Test Framework:** NUnit + SpecFlow
+- **Code Coverage:** Collected but not enforced
+
+### Recommended Additions
+1. **Minimum Code Coverage:** 80%
+2. **Mutation Testing:** Stryker.NET
+3. **Static Analysis:** SonarCloud integration
+4. **Performance Benchmarks:** BenchmarkDotNet for critical paths
+
+---
+
+## 🎯 Prioritized Action Plan
+
+### Sprint 1 (This Week)
+1. Fix broken assertions in HttpExamplesSteps.cs
+2. Remove duplicate project reference
+3. Remove unused variable in RestSharpDriver.cs
+4. Complete README.md sections (How to start, Project structure, Configuration)
+5. Add SECURITY.md
+
+### Sprint 2 (Next Week)
+1. Enable nullable reference types
+2. Add EditorConfig
+3. Add Dependabot configuration
+4. Fix code-quality job to fail on vulnerabilities
+5. Add timeout configuration for RestClient
+
+### Sprint 3 (Following Week)
+1. Add CodeQL security scanning
+2. Add Codecov integration
+3. Implement DELETE and PATCH methods
+4. Add cancellation token support
+5. Add contribution guidelines
+
+### Sprint 4 (Future)
+1. Add issue and PR templates
+2. Add .gitattributes
+3. Add retry policies with Polly
+4. Add structured logging
+5. Add CODEOWNERS file
+
+---
+
+## 🔍 Testing Recommendations
+
+### Current Coverage Gaps
+- No tests for error scenarios
+- No tests for timeout handling
+- No tests for invalid JSON
+- No tests for HTTP error codes (4xx, 5xx)
+
+### Recommended Test Scenarios
+```gherkin
+Scenario: Handle 404 Not Found
+  Given the HTTP 'GET' to the endpoint '/nonexistent' is being send
+  Then the status code should be '404'
+
+Scenario: Handle 500 Internal Server Error
+  Given WireMock returns 500 for endpoint '/api/error'
+  When the HTTP 'GET' to the endpoint '/api/error' is being send
+  Then the status code should be '500'
+
+Scenario: Handle timeout
+  Given WireMock has 5 second delay for endpoint '/api/slow'
+  And the client timeout is 2 seconds
+  When the HTTP 'GET' to the endpoint '/api/slow' is being send
+  Then a timeout exception should be thrown
+```
+
+---
+
+## 📝 Summary
+
+This project is well-architected with excellent foundation. The recommended improvements focus on:
+
+1. **Reliability:** Fix assertion bugs, add error handling
+2. **Security:** Add scanning, vulnerability management
+3. **Maintainability:** Enable null safety, add code standards
+4. **Developer Experience:** Complete documentation, add automation
+5. **Quality:** Enforce coverage, add more test scenarios
+
+**Estimated Effort:** 3-4 sprints for all improvements
+
+**Priority Focus:** Start with critical bugs, then security, then developer experience
+
+---
+
+**Questions?** Open an issue or reach out to the maintainers.
diff --git a/TestFrameworkBoilerplate.Tests.Integration/Drivers/RestSharpDriver.cs b/TestFrameworkBoilerplate.Tests.Integration/Drivers/RestSharpDriver.cs
index a096e8f..dc02650 100644
--- a/TestFrameworkBoilerplate.Tests.Integration/Drivers/RestSharpDriver.cs
+++ b/TestFrameworkBoilerplate.Tests.Integration/Drivers/RestSharpDriver.cs
@@ -22,8 +22,6 @@ public async Task<RestResponse> GetAsync(string endpoint)
     {
         var request = new RestRequest(endpoint);
         var response = await _client.ExecuteAsync(request);
-
-        var a = _wireMockDriver.GetUrl();
         return response;
     }
 
diff --git a/TestFrameworkBoilerplate.Tests.Integration/Steps/HttpExamplesSteps.cs b/TestFrameworkBoilerplate.Tests.Integration/Steps/HttpExamplesSteps.cs
index ebb705b..162e2bb 100644
--- a/TestFrameworkBoilerplate.Tests.Integration/Steps/HttpExamplesSteps.cs
+++ b/TestFrameworkBoilerplate.Tests.Integration/Steps/HttpExamplesSteps.cs
@@ -28,10 +28,10 @@ public async Task GivenTheHttpToTheEndpointIsBeingSend(string request, string en
     public void ThenTheResultShouldBe(string expectedJsonName, string statusCode)
     {
         var response = _scenarioContext.GetHttpResponse();
-        response.StatusCode.Equals(Int32.Parse(statusCode));
+        ((int)response.StatusCode).ShouldBe(Int32.Parse(statusCode));
 
         string path = Path.Combine(_directoryPathSettings.Value.ExpectedExampleJsonDirectory, expectedJsonName);
-        
+
         string jsonString = File.ReadAllText(path);
         response.Content.ShouldBe(jsonString);
     }
@@ -40,7 +40,7 @@ public void ThenTheResultShouldBe(string expectedJsonName, string statusCode)
     public void ThenTheResultShouldBe()
     {
         var response = _scenarioContext.GetHttpResponse();
-        response.StatusCode.Equals(StatusCodes.Status201Created);
+        ((int)response.StatusCode).ShouldBe(StatusCodes.Status201Created);
     }
 
     private static Task<RestResponse> SelectRequest(string request, RestSharpDriver restSharpDriver, string endpoint) => request switch
diff --git a/TestFrameworkBoilerplate.Tests.Integration/TestFrameworkBoilerplate.Tests.Integration.csproj b/TestFrameworkBoilerplate.Tests.Integration/TestFrameworkBoilerplate.Tests.Integration.csproj
index ec36367..83fe623 100644
--- a/TestFrameworkBoilerplate.Tests.Integration/TestFrameworkBoilerplate.Tests.Integration.csproj
+++ b/TestFrameworkBoilerplate.Tests.Integration/TestFrameworkBoilerplate.Tests.Integration.csproj
@@ -30,10 +30,6 @@
       <ProjectReference Include="..\TestFrameworkBoilerplate.Tests.WireMock\TestFrameworkBoilerplate.Tests.WireMock.csproj" />
     </ItemGroup>
 
-    <ItemGroup>
-      <ProjectReference Include="..\TestFrameworkBoilerplate.Tests.WireMock\TestFrameworkBoilerplate.Tests.WireMock.csproj" />
-    </ItemGroup>
-
     <ItemGroup>
       <None Update="ExampleJsons\GetExampleResponse.json">
         <CopyToOutputDirectory>Always</CopyToOutputDirectory>