feat: Update documentation for BeforeAll/AfterAll scripts to clarify intended use and provide examples for managing external test resources

Author: MariusStorhaug

specs/001-building-on-this/data-model.md

@@ -83,17 +83,21 @@ This document defines the data structures, contracts, and entities for the setup
 
 **BeforeAll.ps1**:
 - **Location**: `tests/BeforeAll.ps1` (root tests folder only)
-- **Purpose**: Setup test environment before all test matrix jobs
+- **Purpose**: Setup external test resources before all test matrix jobs - resources that are independent of test platform/OS
+- **Intended Use**: Deploy cloud infrastructure via APIs, create external database instances, initialize test data in third-party services
+- **NOT Intended For**: OS-specific dependencies, platform-specific test files, test-specific resources for individual matrix combinations
 - **Execution Context**: Runs in tests directory with full access to environment secrets
 - **Error Handling**: Failures halt testing workflow
-- **Example Use Cases**: Deploy test infrastructure, initialize test data, configure test environment
+- **Example Use Cases**: Deploy Azure/AWS resources via APIs, create external PostgreSQL databases, initialize SaaS test accounts
 
 **AfterAll.ps1**:
 - **Location**: `tests/AfterAll.ps1` (root tests folder only)
-- **Purpose**: Cleanup test environment after all test matrix jobs
+- **Purpose**: Cleanup external test resources after all test matrix jobs - resources that are independent of test platform/OS
+- **Intended Use**: Remove cloud infrastructure via APIs, delete external database instances, cleanup test data in third-party services
+- **NOT Intended For**: OS-specific cleanup, platform-specific file removal, test-specific cleanup for individual matrix combinations
 - **Execution Context**: Runs in tests directory with full access to environment secrets
 - **Error Handling**: Failures logged but don't halt workflow
-- **Example Use Cases**: Remove test resources, cleanup databases, tear down test infrastructure
+- **Example Use Cases**: Delete Azure/AWS resources via APIs, remove external databases, cleanup SaaS test accounts
 
 **Script Contract**:
 - Scripts can access all environment variables (secrets)

specs/001-building-on-this/plan.md

@@ -31,7 +31,7 @@
 - Phase 3-4: Implementation execution (manual or via tools)
 
 ## Summary
-Extract BeforeAll/AfterAll test setup/teardown logic from Test-ModuleLocal.yml into a reusable local composite action. This reduces workflow duplication, improves maintainability, and enables reuse across workflows. The single composite action will accept a mode parameter (before/after) to control which script to execute (BeforeAll.ps1 or AfterAll.ps1) and error handling behavior. The action will be located at `.github/actions/setup-test/action.yml` and will integrate with existing PSModule/GitHub-Script and PSModule/Install-PSModuleHelpers actions.
+Extract BeforeAll/AfterAll test setup/teardown logic from Test-ModuleLocal.yml into a reusable local composite action. This reduces workflow duplication, improves maintainability, and enables reuse across workflows. The single composite action will accept a mode parameter (before/after) to control which script to execute (BeforeAll.ps1 or AfterAll.ps1) and error handling behavior. The action will be located at `.github/actions/setup-test/action.yml` and will integrate with existing PSModule/GitHub-Script and PSModule/Install-PSModuleHelpers actions. Documentation will clearly explain that BeforeAll/AfterAll scripts are intended for managing external test resources (cloud infrastructure, external databases, third-party services) that are independent of the test platform/OS, while test-specific resources should be created within the tests themselves.
 
 ## Technical Context
 **Language/Version**: PowerShell 7.4+ (GitHub Actions composite actions)
@@ -260,7 +260,12 @@ The /tasks command will load `.specify/templates/tasks-template.md` and generate
 
 **From documentation requirements**:
 - Task: Update Process-PSModule README with composite action documentation
-- Task: Update Template-PSModule with example usage
+- Task: Create comprehensive BeforeAll/AfterAll usage documentation explaining:
+  * Intended purpose: external test resource setup (cloud infrastructure, external databases, third-party services via APIs)
+  * Clear distinction: external resources in BeforeAll/AfterAll vs. test-specific resources within tests
+  * Examples: deploying Azure resources, initializing external databases, creating test data in SaaS platforms
+  * Guidance on when to use BeforeAll/AfterAll vs. in-test setup for OS/platform-specific resources
+- Task: Update Template-PSModule with example BeforeAll/AfterAll scripts showing external resource management
 - Task: Create migration guide for nested script consolidation
 - Task: Update .github/copilot-instructions.md (already done in Phase 1)
 
@@ -274,12 +279,12 @@ The /tasks command will load `.specify/templates/tasks-template.md` and generate
    - action.yml structure and script logic can be developed in parallel
    - Different test scenarios can be validated in parallel
 
-**Estimated Task Count**: ~30-35 tasks
+**Estimated Task Count**: ~32-37 tasks
 - Setup: 2 tasks (directory structure, test repository)
 - Composite Action: 8-10 tasks (action.yml, script implementation)
 - Workflow Integration: 4 tasks (modify jobs, verify dependencies)
 - Testing: 7 tasks (integration test scenarios)
-- Documentation: 4 tasks (README, migration guide, templates)
+- Documentation: 6 tasks (README, usage documentation, examples, migration guide, templates)
 
 **Task Priorities**:
 - P0 (Critical Path): Composite action implementation, workflow integration

specs/001-building-on-this/quickstart.md

@@ -8,6 +8,45 @@
 
 This quickstart provides a minimal integration path and validation steps for the setup-test composite action. Follow these steps to verify the feature works as expected.
 
+## Intended Use Case (FR-021)
+
+**BeforeAll/AfterAll scripts are designed for managing external test resources** that are independent of the test platform/OS. These scripts should:
+
+✅ **DO use for**:
+- Deploying cloud infrastructure via APIs (Azure, AWS, GCP)
+- Creating external database instances or schemas
+- Initializing test data in third-party SaaS platforms
+- Setting up API test environments
+- Configuring external services that all tests will use
+
+❌ **DON'T use for**:
+- Installing OS-specific dependencies (do this in test setup)
+- Creating platform-specific test files (do this within tests)
+- Test-specific resources for individual matrix combinations (do this in tests)
+
+**Example BeforeAll.ps1** (External Resources):
+```powershell
+# Deploy Azure resources for testing
+Write-Host "Creating Azure test resources..."
+az group create --name "test-rg-$env:GITHUB_RUN_ID" --location eastus
+az storage account create --name "teststorage$env:GITHUB_RUN_ID" --resource-group "test-rg-$env:GITHUB_RUN_ID"
+
+# Initialize external database
+Write-Host "Creating test database..."
+Invoke-RestMethod -Uri "https://api.example.com/databases" -Method POST -Body @{name="test-db-$env:GITHUB_RUN_ID"}
+```
+
+**Example AfterAll.ps1** (Cleanup External Resources):
+```powershell
+# Remove Azure resources
+Write-Host "Cleaning up Azure test resources..."
+az group delete --name "test-rg-$env:GITHUB_RUN_ID" --yes --no-wait
+
+# Delete external database
+Write-Host "Removing test database..."
+Invoke-RestMethod -Uri "https://api.example.com/databases/test-db-$env:GITHUB_RUN_ID" -Method DELETE
+```
+
 ## Prerequisites
 
 - Process-PSModule repository checked out on branch `001-building-on-this`