diff --git a/.github/prompts/analyze.prompt.md b/.github/prompts/analyze.prompt.md index 2e098099..28add113 100644 --- a/.github/prompts/analyze.prompt.md +++ b/.github/prompts/analyze.prompt.md @@ -61,9 +61,9 @@ Execution steps: 5. Severity assignment heuristic: - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality. - - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion. - - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case. - - LOW: Style/wording improvements, minor redundancy not affecting execution order. + - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, or untestable acceptance criterion. + - MEDIUM: Terminology drift, missing non-functional task coverage, or underspecified edge case. + - LOW: Style/wording improvements, or minor redundancy not affecting execution order. 6. Produce a Markdown report (no file writes) with sections: @@ -95,9 +95,9 @@ Execution steps: * Critical Issues Count 7. At end of report, output a concise Next Actions block: - - If CRITICAL issues exist: Recommend resolving before `/implement`. - - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions. - - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'". + - If CRITICAL issues exist: Recommend resolving them before `/implement`. + - If only LOW/MEDIUM issues: User may proceed, but provide improvement suggestions. + - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", or "Manually edit tasks.md to add coverage for 'performance-metrics'". 8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) diff --git a/.github/prompts/clarify.prompt.md b/.github/prompts/clarify.prompt.md index 06e8a983..4b57b4d7 100644 --- a/.github/prompts/clarify.prompt.md +++ b/.github/prompts/clarify.prompt.md @@ -79,10 +79,10 @@ Execution steps: - Information is better deferred to planning phase (note internally) 3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - - Maximum of 5 total questions across the whole session. + - Maximum of 5 total questions across the entire session. - Each question must be answerable with EITHER: * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR - * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + * A one-word / short‑phrase answer (explicitly constrain: "Answer in ≤5 words"). - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). @@ -102,9 +102,9 @@ Execution steps: | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) | ``` - - For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`. + - For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (≤5 words)`. - After the user answers: - * Validate the answer maps to one option or fits the <=5 word constraint. + * Validate the answer maps to one option or fits the ≤5 word constraint. * If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance). * Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question. - Stop asking further questions when: diff --git a/.github/prompts/constitution.prompt.md b/.github/prompts/constitution.prompt.md index 23341d5e..36eccc08 100644 --- a/.github/prompts/constitution.prompt.md +++ b/.github/prompts/constitution.prompt.md @@ -16,7 +16,7 @@ Follow this execution flow: 1. Load the existing constitution template at `.specify/memory/constitution.md`. - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`. - **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly. + **IMPORTANT**: The user might require fewer or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the document accordingly. 2. Collect/derive values for placeholders: - If user input (conversation) supplies a value, use it. @@ -52,7 +52,7 @@ Follow this execution flow: 6. Validation before final output: - No remaining unexplained bracket tokens. - Version line matches report. - - Dates ISO format YYYY-MM-DD. + - Dates in ISO format (YYYY-MM-DD). - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate). 7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite). diff --git a/.github/prompts/implement.prompt.md b/.github/prompts/implement.prompt.md index c3fb21ef..200f5130 100644 --- a/.github/prompts/implement.prompt.md +++ b/.github/prompts/implement.prompt.md @@ -34,19 +34,19 @@ $ARGUMENTS - **Validation checkpoints**: Verify each phase completion before proceeding 5. Implementation execution rules: - - **Setup first**: Initialize project structure, dependencies, configuration + - **Setup first**: Initialize project structure, dependencies, and configuration - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios - - **Core development**: Implement models, services, CLI commands, endpoints - - **Integration work**: Database connections, middleware, logging, external services - - **Polish and validation**: Unit tests, performance optimization, documentation + - **Core development**: Implement models, services, CLI commands, and endpoints + - **Integration work**: Database connections, middleware, logging, and external services + - **Polish and validation**: Unit tests, performance optimization, and documentation 6. Progress tracking and error handling: - Report progress after each completed task - Halt execution if any non-parallel task fails - - For parallel tasks [P], continue with successful tasks, report failed ones + - For parallel tasks [P], continue with successful tasks and report failed ones - Provide clear error messages with context for debugging - Suggest next steps if implementation cannot proceed - - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file. + - **IMPORTANT**: For completed tasks, make sure to mark the task as [X] in the tasks file. 7. Completion validation: - Verify all required tasks are completed diff --git a/.github/prompts/tasks.prompt.md b/.github/prompts/tasks.prompt.md index a09cdf50..f9696524 100644 --- a/.github/prompts/tasks.prompt.md +++ b/.github/prompts/tasks.prompt.md @@ -35,7 +35,7 @@ $ARGUMENTS 4. Task generation rules: - Each contract file → contract test task marked [P] - Each entity in data-model → model creation task marked [P] - - Each endpoint → implementation task (not parallel if shared files) + - Each endpoint → implementation task (not parallel if files are shared) - Each user story → integration test marked [P] - Different files = can be parallel [P] - Same file = sequential (no [P]) @@ -61,4 +61,4 @@ $ARGUMENTS Context for task generation: $ARGUMENTS -The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context. +The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without requiring additional context. diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 92a4b08d..d3ebb533 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -120,9 +120,9 @@ The `src/` folder contains the module source code that Build-PSModule compiles i - `data/` - Configuration data files (`.psd1`) loaded as module variables - `formats/` - Format definition files (`.ps1xml`) for object display - `functions/private/` - Private functions (internal implementation) - - Supports subdirectories for grouping (e.g., `functions/public/CoponentA/`, `functions/public/ComponentB/`) + - Supports subdirectories for grouping (e.g., `functions/public/ComponentA/`, `functions/public/ComponentB/`) - `functions/public/` - Public functions (exported to module consumers) - - Supports subdirectories for grouping (e.g., `functions/public/CoponentA/`, `functions/public/ComponentB/`) + - Supports subdirectories for grouping (e.g., `functions/public/ComponentA/`, `functions/public/ComponentB/`) - Optional category documentation files (e.g., `functions/public/PSModule/PSModule.md`) - `init/` - Initialization scripts (executed first during module load) - `modules/` - Nested PowerShell modules (`.psm1`) or additional assemblies diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 0fad4eb9..ae3e2fbc 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -12,8 +12,8 @@ → Set Structure Decision based on project type 3. Fill the Constitution Check section based on the content of the constitution document. 4. Evaluate Constitution Check section below - → If violations exist: Document in Complexity Tracking - → If no justification possible: ERROR "Simplify approach first" + → If violations exist: Document them in Complexity Tracking + → If no justification is possible: ERROR "Simplify approach first" → Update Progress Tracking: Initial Constitution Check 5. Execute Phase 0 → research.md → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns" @@ -35,15 +35,15 @@ ## Technical Context -**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION] -**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION] -**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A] -**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION] -**Target Platform**: [e.g., Linux server, iOS 15+, Wasm or NEEDS CLARIFICATION] +**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75, or NEEDS CLARIFICATION] +**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM, or NEEDS CLARIFICATION] +**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files, or N/A] +**Testing**: [e.g., pytest, XCTest, cargo test, or NEEDS CLARIFICATION] +**Target Platform**: [e.g., Linux server, iOS 15+, Wasm, or NEEDS CLARIFICATION] **Project Type**: [single/web/mobile - determines source structure] -**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION] -**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION] -**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION] +**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps, or NEEDS CLARIFICATION] +**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable, or NEEDS CLARIFICATION] +**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens, or NEEDS CLARIFICATION] ## Constitution Check diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md index c675f825..82dece15 100644 --- a/.specify/templates/spec-template.md +++ b/.specify/templates/spec-template.md @@ -18,7 +18,7 @@ 5. Generate Functional Requirements → Each requirement must be testable → Mark ambiguous requirements -6. Identify Key Entities (if data involved) +6. Identify Key Entities (if data is involved) 7. Run Review Checklist → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties" → If implementation details found: ERROR "Remove tech details" @@ -88,7 +88,7 @@ Example of marking unclear requirements: ### Key Entities *(include if feature involves data)* -- **[Entity 1]**: [What it represents, key attributes without implementation] +- **[Entity 1]**: [What it represents, key attributes without implementation details] - **[Entity 2]**: [What it represents, relationships to other entities] --- diff --git a/README.md b/README.md index 3b793176..207228f5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Process-PSModule -A workflow for crafting PowerShell modules using the PSModule framework, which builds, tests and publishes PowerShell modules to the PowerShell +A workflow for crafting PowerShell modules using the PSModule framework, which builds, tests, and publishes PowerShell modules to the PowerShell Gallery and produces documentation that is published to GitHub Pages. The workflow is used by all PowerShell modules in the PSModule organization. ## How to get started @@ -18,7 +18,7 @@ Gallery and produces documentation that is published to GitHub Pages. The workfl ## How it works -The workflow is designed to be trigger on pull requests to the repository's default branch. +The workflow is designed to be triggered on pull requests to the repository's default branch. When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow will run. Depending on the labels in the pull requests, the workflow will result in different outcomes. @@ -31,19 +31,23 @@ Depending on the labels in the pull requests, the workflow will result in differ - [Build module](./.github/workflows/Build-Module.yml) - Compiles the module source code into a PowerShell module. - [Test source code](./.github/workflows/Test-SourceCode.yml) - - Tests the source code in parallel (matrix) using [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#sourcecode-tests) + - Tests the source code in parallel (matrix) using: + - [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#sourcecode-tests) - This produces a json based report that is used to later evaluate the results of the tests. - [Lint source code](./.github/workflows/Lint-SourceCode.yml) - - Lints the source code in parallel (matrix) using [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer). + - Lints the source code in parallel (matrix) using: + - [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer). - This produces a json based report that is used to later evaluate the results of the linter. - [Framework test](./.github/workflows/Test-Module.yml) - - Tests and lints the module in parallel (matrix) using [PSModule framework settings for style and standards foor modules](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#module-tests) + [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer). + - Tests and lints the module in parallel (matrix) using: + - [PSModule framework settings for style and standards for modules](https://github.com/PSModule/Test-PSModule?tab=readme-ov-file#module-tests) + - [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer). - This produces a json based report that is used to later evaluate the results of the tests. - [Test module](./.github/workflows/Test-ModuleLocal.yml) - Import and tests the module in parallel (matrix) using Pester tests from the module repository. - Supports setup and teardown scripts executed via separate dedicated jobs: - - **BeforeAll.ps1**: Runs once before all test matrix jobs to set up test environment (e.g., deploy infrastructure, download test data) - - **AfterAll.ps1**: Runs once after all test matrix jobs complete to clean up test environment (e.g., remove test resources, cleanup databases) + - `BeforeAll`: Runs once before all test matrix jobs to set up test environment (e.g., deploy infrastructure, download test data) + - `AfterAll`: Runs once after all test matrix jobs complete to clean up test environment (e.g., remove test resources, cleanup databases) - Setup/teardown scripts are automatically detected in test directories and executed with the same environment variables as tests - This produces a json based report that is used to later evaluate the results of the tests. - [Get test results](./.github/workflows/Get-TestResults.yml) @@ -53,16 +57,19 @@ Depending on the labels in the pull requests, the workflow will result in differ - Gathers the code coverage from the previous steps and creates a summary of the results. - If the code coverage is below the target, the workflow will fail here. - [Build docs](./.github/workflows/Build-Docs.yml) - - Generates documentation and lints the documentation using [super-linter](https://github.com/super-linter/super-linter). + - Generates documentation and lints the documentation using: + - [super-linter](https://github.com/super-linter/super-linter). - [Build site](./.github/workflows/Build-Site.yml) - - Generates a static site using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). + - Generates a static site using: + - [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). - [Publish site](./.github/workflows/Publish-Site.yml) - - Publishes the static site with the module documentationto GitHub Pages. + - Publishes the static site with the module documentation to GitHub Pages. - [Publish module](./.github/workflows/Publish-Module.yml) - Publishes the module to the PowerShell Gallery. - Creates a release on the GitHub repository. To use the workflow, create a new file in the `.github/workflows` directory of the module repository and add the following content. +
Workflow suggestion @@ -100,10 +107,9 @@ jobs: ## Configuration The workflow is configured using a settings file in the module repository. -The file can be a `JSON`, `YAML` or `PSD1` file. By default it will look for `.github/PSModule.yml`. +The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`. The following settings are available in the settings file: -Here's a Markdown-formatted table describing your PowerShell object structure clearly and concisely: | Name | Type | Description | Default | |----------------------------------------|-----------|----------------------------------------------------------------------------------------------------------|---------------------| @@ -265,19 +271,18 @@ Build: The workflow supports automatic execution of setup and teardown scripts for module tests: -#### BeforeAll.ps1 -- **Location**: Place in your test directories (e.g., `tests/BeforeAll.ps1`) -- **Purpose**: Runs once before all test matrix jobs to prepare the test environment -- **Use cases**: Deploy test infrastructure, download test data, initialize databases, configure services -- **Environment**: Has access to the same environment variables as your tests (secrets, GitHub token, etc.) +- Scripts are automatically detected and executed if present +- If no scripts are found, the workflow continues normally + +#### Setup - `BeforeAll.ps1` + +- Place in your test directories (`tests/BeforeAll.ps1`) +- Runs once before all test matrix jobs to prepare the test environment +- Deploy test infrastructure, download test data, initialize databases, or configure services +- Has access to the same environment variables as your tests (secrets, GitHub token, etc.) -#### AfterAll.ps1 -- **Location**: Place in your test directories (e.g., `tests/AfterAll.ps1`) -- **Purpose**: Runs once after all test matrix jobs complete to clean up the test environment -- **Use cases**: Remove test resources, cleanup databases, stop services, upload artifacts -- **Environment**: Has access to the same environment variables as your tests +##### Example - `BeforeAll.ps1` -**Example BeforeAll.ps1:** ```powershell Write-Host "Setting up test environment..." # Deploy test infrastructure @@ -286,7 +291,15 @@ Write-Host "Setting up test environment..." Write-Host "Test environment ready!" ``` -**Example AfterAll.ps1:** +#### Teardown - `AfterAll.ps1` + +- Place in your test directories (`tests/AfterAll.ps1`) +- Runs once after all test matrix jobs complete to clean up the test environment +- Remove test resources, clean up databases, stop services, or upload artifacts +- Has access to the same environment variables as your tests + +##### Example - `AfterAll.ps1` + ```powershell Write-Host "Cleaning up test environment..." # Remove test resources @@ -295,25 +308,6 @@ Write-Host "Cleaning up test environment..." Write-Host "Cleanup completed!" ``` -**Notes:** -- Scripts are automatically detected and executed if present -- Each unique test directory path is processed only once -- Scripts run with PowerShell and have access to PSModuleHelpers -- If no scripts are found, the workflow continues normally - -**Execution Order:** - -The workflow executes setup and teardown scripts using separate dedicated jobs with the following order: - -```plaintext -BeforeAll-ModuleLocal → Test-ModuleLocal (matrix) → AfterAll-ModuleLocal → Get-TestResults/Get-CodeCoverage -``` - -- **BeforeAll-ModuleLocal**: Runs once before all test matrix jobs -- **Test-ModuleLocal**: Runs tests in parallel matrix configuration -- **AfterAll-ModuleLocal**: Runs once after all test matrix jobs complete (always executes for cleanup, even if tests fail) -- **Get-TestResults/Get-CodeCoverage**: Process results after cleanup is complete - ### Secrets The following secrets are used by the workflow. They can be automatically provided (if available) by setting the `secrets: inherit` @@ -332,9 +326,7 @@ in the workflow file. ## Permissions -The action requires the following permissions: - -If running the action in a restrictive mode, the following permissions needs to be granted to the action: +If running the action in a restrictive mode, the following permissions need to be granted to the action: ```yaml permissions: @@ -362,4 +354,4 @@ Process-PSModule follows: - [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) and [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules) - [GitHub Flow specifications](https://docs.github.com/en/get-started/using-github/github-flow) - [SemVer 2.0.0 specifications](https://semver.org) -- [Continiuous Delivery practices](https://en.wikipedia.org/wiki/Continuous_delivery) +- [Continuous Delivery practices](https://en.wikipedia.org/wiki/Continuous_delivery)