workspace-architect 1.3.0

package/assets/instructions/powershell-pester-5.instructions.md

@@ -0,0 +1,197 @@
+---
+applyTo: '**/*.Tests.ps1'
+description: 'PowerShell Pester testing best practices based on Pester v5 conventions'
+---
+
+# PowerShell Pester v5 Testing Guidelines
+
+This guide provides PowerShell-specific instructions for creating automated tests using PowerShell Pester v5 module. Follow PowerShell cmdlet development guidelines in [powershell.instructions.md](./powershell.instructions.md) for general PowerShell scripting best practices.
+
+## File Naming and Structure
+
+- **File Convention:** Use `*.Tests.ps1` naming pattern
+- **Placement:** Place test files next to tested code or in dedicated test directories
+- **Import Pattern:** Use `BeforeAll { . $PSScriptRoot/FunctionName.ps1 }` to import tested functions
+- **No Direct Code:** Put ALL code inside Pester blocks (`BeforeAll`, `Describe`, `Context`, `It`, etc.)
+
+## Test Structure Hierarchy
+
+```powershell
+BeforeAll { # Import tested functions }
+Describe 'FunctionName' {
+    Context 'When condition' {
+        BeforeAll { # Setup for context }
+        It 'Should behavior' { # Individual test }
+        AfterAll { # Cleanup for context }
+    }
+}
+```
+
+## Core Keywords
+
+- **`Describe`**: Top-level grouping, typically named after function being tested
+- **`Context`**: Sub-grouping within Describe for specific scenarios
+- **`It`**: Individual test cases, use descriptive names
+- **`Should`**: Assertion keyword for test validation
+- **`BeforeAll/AfterAll`**: Setup/teardown once per block
+- **`BeforeEach/AfterEach`**: Setup/teardown before/after each test
+
+## Setup and Teardown
+
+- **`BeforeAll`**: Runs once at start of containing block, use for expensive operations
+- **`BeforeEach`**: Runs before every `It` in block, use for test-specific setup
+- **`AfterEach`**: Runs after every `It`, guaranteed even if test fails
+- **`AfterAll`**: Runs once at end of block, use for cleanup
+- **Variable Scoping**: `BeforeAll` variables available to child blocks (read-only), `BeforeEach/It/AfterEach` share same scope
+
+## Assertions (Should)
+
+- **Basic Comparisons**: `-Be`, `-BeExactly`, `-Not -Be`
+- **Collections**: `-Contain`, `-BeIn`, `-HaveCount`
+- **Numeric**: `-BeGreaterThan`, `-BeLessThan`, `-BeGreaterOrEqual`
+- **Strings**: `-Match`, `-Like`, `-BeNullOrEmpty`
+- **Types**: `-BeOfType`, `-BeTrue`, `-BeFalse`
+- **Files**: `-Exist`, `-FileContentMatch`
+- **Exceptions**: `-Throw`, `-Not -Throw`
+
+## Mocking
+
+- **`Mock CommandName { ScriptBlock }`**: Replace command behavior
+- **`-ParameterFilter`**: Mock only when parameters match condition
+- **`-Verifiable`**: Mark mock as requiring verification
+- **`Should -Invoke`**: Verify mock was called specific number of times
+- **`Should -InvokeVerifiable`**: Verify all verifiable mocks were called
+- **Scope**: Mocks default to containing block scope
+
+```powershell
+Mock Get-Service { @{ Status = 'Running' } } -ParameterFilter { $Name -eq 'TestService' }
+Should -Invoke Get-Service -Exactly 1 -ParameterFilter { $Name -eq 'TestService' }
+```
+
+## Test Cases (Data-Driven Tests)
+
+Use `-TestCases` or `-ForEach` for parameterized tests:
+
+```powershell
+It 'Should return <Expected> for <Input>' -TestCases @(
+    @{ Input = 'value1'; Expected = 'result1' }
+    @{ Input = 'value2'; Expected = 'result2' }
+) {
+    Get-Function $Input | Should -Be $Expected
+}
+```
+
+## Data-Driven Tests
+
+- **`-ForEach`**: Available on `Describe`, `Context`, and `It` for generating multiple tests from data
+- **`-TestCases`**: Alias for `-ForEach` on `It` blocks (backwards compatibility)
+- **Hashtable Data**: Each item defines variables available in test (e.g., `@{ Name = 'value'; Expected = 'result' }`)
+- **Array Data**: Uses `$_` variable for current item
+- **Templates**: Use `<variablename>` in test names for dynamic expansion
+
+```powershell
+# Hashtable approach
+It 'Returns <Expected> for <Name>' -ForEach @(
+    @{ Name = 'test1'; Expected = 'result1' }
+    @{ Name = 'test2'; Expected = 'result2' }
+) { Get-Function $Name | Should -Be $Expected }
+
+# Array approach
+It 'Contains <_>' -ForEach 'item1', 'item2' { Get-Collection | Should -Contain $_ }
+```
+
+## Tags
+
+- **Available on**: `Describe`, `Context`, and `It` blocks
+- **Filtering**: Use `-TagFilter` and `-ExcludeTagFilter` with `Invoke-Pester`
+- **Wildcards**: Tags support `-like` wildcards for flexible filtering
+
+```powershell
+Describe 'Function' -Tag 'Unit' {
+    It 'Should work' -Tag 'Fast', 'Stable' { }
+    It 'Should be slow' -Tag 'Slow', 'Integration' { }
+}
+
+# Run only fast unit tests
+Invoke-Pester -TagFilter 'Unit' -ExcludeTagFilter 'Slow'
+```
+
+## Skip
+
+- **`-Skip`**: Available on `Describe`, `Context`, and `It` to skip tests
+- **Conditional**: Use `-Skip:$condition` for dynamic skipping
+- **Runtime Skip**: Use `Set-ItResult -Skipped` during test execution (setup/teardown still run)
+
+```powershell
+It 'Should work on Windows' -Skip:(-not $IsWindows) { }
+Context 'Integration tests' -Skip { }
+```
+
+## Error Handling
+
+- **Continue on Failure**: Use `Should.ErrorAction = 'Continue'` to collect multiple failures
+- **Stop on Critical**: Use `-ErrorAction Stop` for pre-conditions
+- **Test Exceptions**: Use `{ Code } | Should -Throw` for exception testing
+
+## Best Practices
+
+- **Descriptive Names**: Use clear test descriptions that explain behavior
+- **AAA Pattern**: Arrange (setup), Act (execute), Assert (verify)
+- **Isolated Tests**: Each test should be independent
+- **Avoid Aliases**: Use full cmdlet names (`Where-Object` not `?`)
+- **Single Responsibility**: One assertion per test when possible
+- **Test File Organization**: Group related tests in Context blocks. Context blocks can be nested.
+
+## Example Test Pattern
+
+```powershell
+BeforeAll {
+    . $PSScriptRoot/Get-UserInfo.ps1
+}
+
+Describe 'Get-UserInfo' {
+    Context 'When user exists' {
+        BeforeAll {
+            Mock Get-ADUser { @{ Name = 'TestUser'; Enabled = $true } }
+        }
+
+        It 'Should return user object' {
+            $result = Get-UserInfo -Username 'TestUser'
+            $result | Should -Not -BeNullOrEmpty
+            $result.Name | Should -Be 'TestUser'
+        }
+
+        It 'Should call Get-ADUser once' {
+            Get-UserInfo -Username 'TestUser'
+            Should -Invoke Get-ADUser -Exactly 1
+        }
+    }
+
+    Context 'When user does not exist' {
+        BeforeAll {
+            Mock Get-ADUser { throw "User not found" }
+        }
+
+        It 'Should throw exception' {
+            { Get-UserInfo -Username 'NonExistent' } | Should -Throw "*not found*"
+        }
+    }
+}
+```
+
+## Configuration
+
+Configuration is defined **outside** test files when calling `Invoke-Pester` to control execution behavior.
+
+```powershell
+# Create configuration (Pester 5.2+)
+$config = New-PesterConfiguration
+$config.Run.Path = './Tests'
+$config.Output.Verbosity = 'Detailed'
+$config.TestResult.Enabled = $true
+$config.TestResult.OutputFormat = 'NUnitXml'
+$config.Should.ErrorAction = 'Continue'
+Invoke-Pester -Configuration $config
+```
+
+**Key Sections**: Run (Path, Exit), Filter (Tag, ExcludeTag), Output (Verbosity), TestResult (Enabled, OutputFormat), CodeCoverage (Enabled, Path), Should (ErrorAction), Debug

package/assets/instructions/powershell.instructions.md

@@ -0,0 +1,356 @@
+---
+applyTo: '**/*.ps1,**/*.psm1'
+description: 'PowerShell cmdlet and scripting best practices based on Microsoft guidelines'
+---
+
+# PowerShell Cmdlet Development Guidelines
+
+This guide provides PowerShell-specific instructions to help GitHub Copilot generate idiomatic,
+safe, and maintainable scripts. It aligns with Microsoft’s PowerShell cmdlet development guidelines.
+
+## Naming Conventions
+
+- **Verb-Noun Format:**
+  - Use approved PowerShell verbs (Get-Verb)
+  - Use singular nouns
+  - PascalCase for both verb and noun
+  - Avoid special characters and spaces
+
+- **Parameter Names:**
+  - Use PascalCase
+  - Choose clear, descriptive names
+  - Use singular form unless always multiple
+  - Follow PowerShell standard names
+
+- **Variable Names:**
+  - Use PascalCase for public variables
+  - Use camelCase for private variables
+  - Avoid abbreviations
+  - Use meaningful names
+
+- **Alias Avoidance:**
+  - Use full cmdlet names
+  - Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci)
+  - Document any custom aliases
+  - Use full parameter names
+
+### Example
+
+```powershell
+function Get-UserProfile {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Username,
+
+        [Parameter()]
+        [ValidateSet('Basic', 'Detailed')]
+        [string]$ProfileType = 'Basic'
+    )
+
+    process {
+        # Logic here
+    }
+}
+```
+
+## Parameter Design
+
+- **Standard Parameters:**
+  - Use common parameter names (`Path`, `Name`, `Force`)
+  - Follow built-in cmdlet conventions
+  - Use aliases for specialized terms
+  - Document parameter purpose
+
+- **Parameter Names:**
+  - Use singular form unless always multiple
+  - Choose clear, descriptive names
+  - Follow PowerShell conventions
+  - Use PascalCase formatting
+
+- **Type Selection:**
+  - Use common .NET types
+  - Implement proper validation
+  - Consider ValidateSet for limited options
+  - Enable tab completion where possible
+
+- **Switch Parameters:**
+  - Use [switch] for boolean flags
+  - Avoid $true/$false parameters
+  - Default to $false when omitted
+  - Use clear action names
+
+### Example
+
+```powershell
+function Set-ResourceConfiguration {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$Name,
+
+        [Parameter()]
+        [ValidateSet('Dev', 'Test', 'Prod')]
+        [string]$Environment = 'Dev',
+
+        [Parameter()]
+        [switch]$Force,
+
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [string[]]$Tags
+    )
+
+    process {
+        # Logic here
+    }
+}
+```
+
+## Pipeline and Output
+
+- **Pipeline Input:**
+  - Use `ValueFromPipeline` for direct object input
+  - Use `ValueFromPipelineByPropertyName` for property mapping
+  - Implement Begin/Process/End blocks for pipeline handling
+  - Document pipeline input requirements
+
+- **Output Objects:**
+  - Return rich objects, not formatted text
+  - Use PSCustomObject for structured data
+  - Avoid Write-Host for data output
+  - Enable downstream cmdlet processing
+
+- **Pipeline Streaming:**
+  - Output one object at a time
+  - Use process block for streaming
+  - Avoid collecting large arrays
+  - Enable immediate processing
+
+- **PassThru Pattern:**
+  - Default to no output for action cmdlets
+  - Implement `-PassThru` switch for object return
+  - Return modified/created object with `-PassThru`
+  - Use verbose/warning for status updates
+
+### Example
+
+```powershell
+function Update-ResourceStatus {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
+        [string]$Name,
+
+        [Parameter(Mandatory)]
+        [ValidateSet('Active', 'Inactive', 'Maintenance')]
+        [string]$Status,
+
+        [Parameter()]
+        [switch]$PassThru
+    )
+
+    begin {
+        Write-Verbose 'Starting resource status update process'
+        $timestamp = Get-Date
+    }
+
+    process {
+        # Process each resource individually
+        Write-Verbose "Processing resource: $Name"
+
+        $resource = [PSCustomObject]@{
+            Name        = $Name
+            Status      = $Status
+            LastUpdated = $timestamp
+            UpdatedBy   = $env:USERNAME
+        }
+
+        # Only output if PassThru is specified
+        if ($PassThru.IsPresent) {
+            Write-Output $resource
+        }
+    }
+
+    end {
+        Write-Verbose 'Resource status update process completed'
+    }
+}
+```
+
+## Error Handling and Safety
+
+- **ShouldProcess Implementation:**
+  - Use `[CmdletBinding(SupportsShouldProcess = $true)]`
+  - Set appropriate `ConfirmImpact` level
+  - Call `$PSCmdlet.ShouldProcess()` for system changes
+  - Use `ShouldContinue()` for additional confirmations
+
+- **Message Streams:**
+  - `Write-Verbose` for operational details with `-Verbose`
+  - `Write-Warning` for warning conditions
+  - `Write-Error` for non-terminating errors
+  - `throw` for terminating errors
+  - Avoid `Write-Host` except for user interface text
+
+- **Error Handling Pattern:**
+  - Use try/catch blocks for error management
+  - Set appropriate ErrorAction preferences
+  - Return meaningful error messages
+  - Use ErrorVariable when needed
+  - Include proper terminating vs non-terminating error handling
+  - In advanced functions with `[CmdletBinding()]`, prefer `$PSCmdlet.WriteError()` over `Write-Error`
+  - In advanced functions with `[CmdletBinding()]`, prefer `$PSCmdlet.ThrowTerminatingError()` over `throw`
+  - Construct proper ErrorRecord objects with category, target, and exception details
+
+- **Non-Interactive Design:**
+  - Accept input via parameters
+  - Avoid `Read-Host` in scripts
+  - Support automation scenarios
+  - Document all required inputs
+
+### Example
+
+```powershell
+function Remove-UserAccount {
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    param(
+        [Parameter(Mandatory, ValueFromPipeline)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Username,
+
+        [Parameter()]
+        [switch]$Force
+    )
+
+    begin {
+        Write-Verbose 'Starting user account removal process'
+        $ErrorActionPreference = 'Stop'
+    }
+
+    process {
+        try {
+            # Validation
+            if (-not (Test-UserExists -Username $Username)) {
+                $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                    [System.Exception]::new("User account '$Username' not found"),
+                    'UserNotFound',
+                    [System.Management.Automation.ErrorCategory]::ObjectNotFound,
+                    $Username
+                )
+                $PSCmdlet.WriteError($errorRecord)
+                return
+            }
+
+            # Confirmation
+            $shouldProcessMessage = "Remove user account '$Username'"
+            if ($Force -or $PSCmdlet.ShouldProcess($Username, $shouldProcessMessage)) {
+                Write-Verbose "Removing user account: $Username"
+
+                # Main operation
+                Remove-ADUser -Identity $Username -ErrorAction Stop
+                Write-Warning "User account '$Username' has been removed"
+            }
+        } catch [Microsoft.ActiveDirectory.Management.ADException] {
+            $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $_.Exception,
+                'ActiveDirectoryError',
+                [System.Management.Automation.ErrorCategory]::NotSpecified,
+                $Username
+            )
+            $PSCmdlet.ThrowTerminatingError($errorRecord)
+        } catch {
+            $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $_.Exception,
+                'UnexpectedError',
+                [System.Management.Automation.ErrorCategory]::NotSpecified,
+                $Username
+            )
+            $PSCmdlet.ThrowTerminatingError($errorRecord)
+        }
+    }
+
+    end {
+        Write-Verbose 'User account removal process completed'
+    }
+}
+```
+
+## Documentation and Style
+
+- **Comment-Based Help:** Include comment-based help for any public-facing function or cmdlet. Inside the function, add a `<# ... #>` help comment with at least:
+  - `.SYNOPSIS` Brief description
+  - `.DESCRIPTION` Detailed explanation
+  - `.EXAMPLE` sections with practical usage
+  - `.PARAMETER` descriptions
+  - `.OUTPUTS` Type of output returned
+  - `.NOTES` Additional information
+
+- **Consistent Formatting:**
+  - Follow consistent PowerShell style
+  - Use proper indentation (4 spaces recommended)
+  - Opening braces on same line as statement
+  - Closing braces on new line
+  - Use line breaks after pipeline operators
+  - PascalCase for function and parameter names
+  - Avoid unnecessary whitespace
+
+- **Pipeline Support:**
+  - Implement Begin/Process/End blocks for pipeline functions
+  - Use ValueFromPipeline where appropriate
+  - Support pipeline input by property name
+  - Return proper objects, not formatted text
+
+- **Avoid Aliases:** Use full cmdlet names and parameters
+  - Avoid using aliases in scripts (e.g., use Get-ChildItem instead of gci); aliases are acceptable for interactive shell use.
+  - Use `Where-Object` instead of `?` or `where`
+  - Use `ForEach-Object` instead of `%`
+  - Use `Get-ChildItem` instead of `ls` or `dir`
+
+## Full Example: End-to-End Cmdlet Pattern
+
+```powershell
+function New-Resource {
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
+    param(
+        [Parameter(Mandatory = $true,
+            ValueFromPipeline = $true,
+            ValueFromPipelineByPropertyName = $true)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Name,
+
+        [Parameter()]
+        [ValidateSet('Development', 'Production')]
+        [string]$Environment = 'Development'
+    )
+
+    begin {
+        Write-Verbose 'Starting resource creation process'
+    }
+
+    process {
+        try {
+            if ($PSCmdlet.ShouldProcess($Name, 'Create new resource')) {
+                # Resource creation logic here
+                Write-Output ([PSCustomObject]@{
+                        Name        = $Name
+                        Environment = $Environment
+                        Created     = Get-Date
+                    })
+            }
+        } catch {
+            $errorRecord = [System.Management.Automation.ErrorRecord]::new(
+                $_.Exception,
+                'ResourceCreationFailed',
+                [System.Management.Automation.ErrorCategory]::NotSpecified,
+                $Name
+            )
+            $PSCmdlet.ThrowTerminatingError($errorRecord)
+        }
+    }
+
+    end {
+        Write-Verbose 'Completed resource creation process'
+    }
+}
+```

package/assets/instructions/prompt.instructions.md

@@ -0,0 +1,73 @@
+---
+description: 'Guidelines for creating high-quality prompt files for GitHub Copilot'
+applyTo: '**/*.prompt.md'
+---
+
+# Copilot Prompt Files Guidelines
+
+Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.
+
+## Scope and Principles
+- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.
+- Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.
+- Primary references: VS Code documentation on prompt files and organization-specific conventions.
+
+## Frontmatter Requirements
+- Include `description` (single sentence, actionable outcome), `mode` (explicitly choose `ask`, `edit`, or `agent`), and `tools` (minimal set of tool bundles required to fulfill the prompt).
+- Declare `model` when the prompt depends on a specific capability tier; otherwise inherit the active model.
+- Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization.
+- Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity.
+
+## File Naming and Placement
+- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
+- Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).
+
+## Body Structure
+- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.
+- Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.
+- Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.
+- Reference related prompts or instruction files using relative links to aid discoverability.
+
+## Input and Context Handling
+- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.
+- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.
+- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).
+
+## Tool and Permission Guidance
+- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.
+- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.
+- Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.
+
+## Instruction Tone and Style
+- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).
+- Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.
+- Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.
+
+## Output Definition
+- Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”).
+- Include success criteria and failure triggers so Copilot knows when to halt or retry.
+- Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.
+
+## Examples and Reusable Assets
+- Embed Good/Bad examples or scaffolds (Markdown templates, JSON stubs) that the prompt should produce or follow.
+- Maintain reference tables (capabilities, status codes, role descriptions) inline to keep the prompt self-contained. Update these tables when upstream resources change.
+- Link to authoritative documentation instead of duplicating lengthy guidance.
+
+## Quality Assurance Checklist
+- [ ] Frontmatter fields are complete, accurate, and least-privilege.
+- [ ] Inputs include placeholders, default behaviours, and fallbacks.
+- [ ] Workflow covers preparation, execution, and post-processing without gaps.
+- [ ] Output expectations include formatting and storage details.
+- [ ] Validation steps are actionable (commands, diff checks, review prompts).
+- [ ] Security, compliance, and privacy policies referenced by the prompt are current.
+- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.
+
+## Maintenance Guidance
+- Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.
+- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.
+- Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.
+
+## Additional Resources
+- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)
+- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)
+- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)