workspace-architect 1.3.0 → 1.5.0

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

@@ -1,197 +0,0 @@
----
-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

@@ -1,356 +0,0 @@
----
-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

@@ -1,73 +0,0 @@
----
-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)