Skip to content

Commit 7e38e21

Browse files
MariusStorhaugCopilotCopilot
authored
🚀[Feature]: Test Setup & Teardown Support for GitHub Actions Workflows (#191)
## Overview This release introduces **automated test environment management** through `BeforeAll.ps1` and `AfterAll.ps1` scripts, enabling comprehensive setup and teardown capabilities for module tests running in GitHub Actions. This enhancement solves the challenge of managing complex test environments (databases, infrastructure, external services) across parallel test matrices while ensuring proper cleanup regardless of test outcomes. ### 🎯 Main Feature: Test Lifecycle Management #### The Problem Previously, setting up test infrastructure required: - Rate-limiting issue when creating GitHub Repositories for the GitHub PowerShell module, where the setup and teardown happens in the individual test files via BeforeAll and AfterAll blocks. #### The Solution **Dedicated setup and teardown jobs** with automatic script execution: - BeforeAll: Runs once before all test matrix jobs begin. - AfterAll: Runs once after all test matrix jobs complete. #### Configuration No configuration needed! Simply add scripts to your test directory. The workflow automatically detects and executes these scripts when present. ``` your-module/ ├── tests/ │ ├── BeforeAll.ps1 ← Setup script (optional) │ ├── AfterAll.ps1 ← Teardown script (optional) │ └── Module.Tests.ps1 ← The tests that require external setup │ ``` ### Additional: Specification-Driven Development Framework This release also includes an implementation of [spec-kit](https://github.com/github/spec-kit) principles, adding a structured workflow for feature development from specification through implementation. #### What's Included - **Prompt templates** (`.github/prompts/`) for `/specify`, `/clarify`, `/plan`, `/tasks`, `/analyze`, `/implement` commands - **Project constitution** (`.specify/memory/constitution.md`) defining architectural principles: ### Additional Workflow Improvements #### Linter Configuration Updates - Added `VALIDATE_BIOME_FORMAT: false` for Biome formatter - Added `VALIDATE_GITHUB_ACTIONS_ZIZMOR: false` for workflow security scanning - Added `VALIDATE_JSCPD: false` for copy-paste detection - Consistent linting configuration across Build-Docs and Linter workflows #### Test Workflow Enhancements - Environment variables properly scoped at workflow level - Clearer parameter naming (`OSName` vs `OS`) - Improved test execution coordination #### Documentation - Comprehensive setup/teardown guide in [README.md](README.md#setup-and-teardown-scripts) - Inline documentation in all prompt templates and scripts - Usage examples for common test scenarios --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent c67d665 commit 7e38e21

30 files changed

+3062
-282
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Process-PSModule Development Guidelines
2+
3+
Auto-generated from all feature plans. Last updated: 2025-10-01
4+
5+
## Active Technologies
6+
7+
- PowerShell 7.4+ (GitHub Actions composite actions) + PSModule/GitHub-Script@v1, PSModule/Install-PSModuleHelpers@v1 (001-building-on-this)
8+
9+
## Project Structure
10+
11+
```plaintext
12+
src/
13+
tests/
14+
```
15+
16+
## Commands
17+
18+
Add commands for PowerShell 7.4+ (GitHub Actions composite actions)
19+
20+
## Code Style
21+
22+
PowerShell 7.4+ (GitHub Actions composite actions): Follow standard conventions
23+
24+
## Recent Changes
25+
26+
- 001-building-on-this: Added PowerShell 7.4+ (GitHub Actions composite actions) + PSModule/GitHub-Script@v1, PSModule/Install-PSModuleHelpers@v1
27+
28+
<!-- MANUAL ADDITIONS START -->
29+
<!-- MANUAL ADDITIONS END -->

‎.github/prompts/analyze.prompt.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
3+
---
4+
5+
# Analyze
6+
7+
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
8+
9+
User input:
10+
11+
$ARGUMENTS
12+
13+
Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
14+
15+
STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
16+
17+
Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
18+
19+
Execution steps:
20+
21+
1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
22+
- SPEC = FEATURE_DIR/spec.md
23+
- PLAN = FEATURE_DIR/plan.md
24+
- TASKS = FEATURE_DIR/tasks.md
25+
Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
26+
27+
2. Load artifacts:
28+
- Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
29+
- Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
30+
- Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
31+
- Load constitution `.specify/memory/constitution.md` for principle validation.
32+
33+
3. Build internal semantic models:
34+
- Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
35+
- User story/action inventory.
36+
- Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
37+
- Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
38+
39+
4. Detection passes:
40+
A. Duplication detection:
41+
- Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.
42+
B. Ambiguity detection:
43+
- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.
44+
- Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).
45+
C. Underspecification:
46+
- Requirements with verbs but missing object or measurable outcome.
47+
- User stories missing acceptance criteria alignment.
48+
- Tasks referencing files or components not defined in spec/plan.
49+
D. Constitution alignment:
50+
- Any requirement or plan element conflicting with a MUST principle.
51+
- Missing mandated sections or quality gates from constitution.
52+
E. Coverage gaps:
53+
- Requirements with zero associated tasks.
54+
- Tasks with no mapped requirement/story.
55+
- Non-functional requirements not reflected in tasks (e.g., performance, security).
56+
F. Inconsistency:
57+
- Terminology drift (same concept named differently across files).
58+
- Data entities referenced in plan but absent in spec (or vice versa).
59+
- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).
60+
- Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
61+
62+
5. Severity assignment heuristic:
63+
- CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.
64+
- HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion.
65+
- MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.
66+
- LOW: Style/wording improvements, minor redundancy not affecting execution order.
67+
68+
6. Produce a Markdown report (no file writes) with sections:
69+
70+
```markdown
71+
### Specification Analysis Report
72+
73+
| ID | Category | Severity | Location(s) | Summary | Recommendation |
74+
|----|----------|----------|-------------|---------|----------------|
75+
| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
76+
(Add one row per finding; generate stable IDs prefixed by category initial.)
77+
```
78+
79+
Additional subsections:
80+
- Coverage Summary Table:
81+
82+
```markdown
83+
| Requirement Key | Has Task? | Task IDs | Notes |
84+
|-----------------|-----------|----------|-------|
85+
```
86+
87+
- Constitution Alignment Issues (if any)
88+
- Unmapped Tasks (if any)
89+
- Metrics:
90+
* Total Requirements
91+
* Total Tasks
92+
* Coverage % (requirements with >=1 task)
93+
* Ambiguity Count
94+
* Duplication Count
95+
* Critical Issues Count
96+
97+
7. At end of report, output a concise Next Actions block:
98+
- If CRITICAL issues exist: Recommend resolving before `/implement`.
99+
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.
100+
- 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'".
101+
102+
8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
103+
104+
Behavior rules:
105+
- NEVER modify files.
106+
- NEVER hallucinate missing sections—if absent, report them.
107+
- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
108+
- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
109+
- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
110+
111+
Context: $ARGUMENTS

‎.github/prompts/clarify.prompt.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
3+
---
4+
5+
# Clarify
6+
7+
The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
8+
9+
User input:
10+
11+
$ARGUMENTS
12+
13+
Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
14+
15+
Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
16+
17+
Execution steps:
18+
19+
1. Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
20+
- `FEATURE_DIR`
21+
- `FEATURE_SPEC`
22+
- (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
23+
- If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment.
24+
25+
2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
26+
27+
Functional Scope & Behavior:
28+
- Core user goals & success criteria
29+
- Explicit out-of-scope declarations
30+
- User roles / personas differentiation
31+
32+
Domain & Data Model:
33+
- Entities, attributes, relationships
34+
- Identity & uniqueness rules
35+
- Lifecycle/state transitions
36+
- Data volume / scale assumptions
37+
38+
Interaction & UX Flow:
39+
- Critical user journeys / sequences
40+
- Error/empty/loading states
41+
- Accessibility or localization notes
42+
43+
Non-Functional Quality Attributes:
44+
- Performance (latency, throughput targets)
45+
- Scalability (horizontal/vertical, limits)
46+
- Reliability & availability (uptime, recovery expectations)
47+
- Observability (logging, metrics, tracing signals)
48+
- Security & privacy (authN/Z, data protection, threat assumptions)
49+
- Compliance / regulatory constraints (if any)
50+
51+
Integration & External Dependencies:
52+
- External services/APIs and failure modes
53+
- Data import/export formats
54+
- Protocol/versioning assumptions
55+
56+
Edge Cases & Failure Handling:
57+
- Negative scenarios
58+
- Rate limiting / throttling
59+
- Conflict resolution (e.g., concurrent edits)
60+
61+
Constraints & Tradeoffs:
62+
- Technical constraints (language, storage, hosting)
63+
- Explicit tradeoffs or rejected alternatives
64+
65+
Terminology & Consistency:
66+
- Canonical glossary terms
67+
- Avoided synonyms / deprecated terms
68+
69+
Completion Signals:
70+
- Acceptance criteria testability
71+
- Measurable Definition of Done style indicators
72+
73+
Misc / Placeholders:
74+
- TODO markers / unresolved decisions
75+
- Ambiguous adjectives ("robust", "intuitive") lacking quantification
76+
77+
For each category with Partial or Missing status, add a candidate question opportunity unless:
78+
- Clarification would not materially change implementation or validation strategy
79+
- Information is better deferred to planning phase (note internally)
80+
81+
3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
82+
- Maximum of 5 total questions across the whole session.
83+
- Each question must be answerable with EITHER:
84+
* A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
85+
* A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
86+
- Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
87+
- 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.
88+
- Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
89+
- Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
90+
- If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
91+
92+
4. Sequential questioning loop (interactive):
93+
- Present EXACTLY ONE question at a time.
94+
- For multiple‑choice questions render options as a Markdown table:
95+
96+
```markdown
97+
| Option | Description |
98+
|--------|-------------|
99+
| A | <Option A description> |
100+
| B | <Option B description> |
101+
| C | <Option C description> (add D/E as needed up to 5) |
102+
| Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
103+
```
104+
105+
- For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
106+
- After the user answers:
107+
* Validate the answer maps to one option or fits the <=5 word constraint.
108+
* If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
109+
* Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
110+
- Stop asking further questions when:
111+
* All critical ambiguities resolved early (remaining queued items become unnecessary), OR
112+
* User signals completion ("done", "good", "no more"), OR
113+
* You reach 5 asked questions.
114+
- Never reveal future queued questions in advance.
115+
- If no valid questions exist at start, immediately report no critical ambiguities.
116+
117+
5. Integration after EACH accepted answer (incremental update approach):
118+
- Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
119+
- For the first integrated answer in this session:
120+
* Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
121+
* Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
122+
- Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
123+
- Then immediately apply the clarification to the most appropriate section(s):
124+
* Functional ambiguity → Update or add a bullet in Functional Requirements.
125+
* User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
126+
* Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
127+
* Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
128+
* Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
129+
* Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
130+
- If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
131+
- Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
132+
- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
133+
- Keep each inserted clarification minimal and testable (avoid narrative drift).
134+
135+
6. Validation (performed after EACH write plus final pass):
136+
- Clarifications session contains exactly one bullet per accepted answer (no duplicates).
137+
- Total asked (accepted) questions ≤ 5.
138+
- Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
139+
- No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
140+
- Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
141+
- Terminology consistency: same canonical term used across all updated sections.
142+
143+
7. Write the updated spec back to `FEATURE_SPEC`.
144+
145+
8. Report completion (after questioning loop ends or early termination):
146+
- Number of questions asked & answered.
147+
- Path to updated spec.
148+
- Sections touched (list names).
149+
- Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
150+
- If any Outstanding or Deferred remain, recommend whether to proceed to `/plan` or run `/clarify` again later post-plan.
151+
- Suggested next command.
152+
153+
Behavior rules:
154+
155+
- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
156+
- If spec file missing, instruct user to run `/specify` first (do not create a new spec here).
157+
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
158+
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
159+
- Respect user early termination signals ("stop", "done", "proceed").
160+
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
161+
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
162+
163+
Context for prioritization: $ARGUMENTS

0 commit comments

Comments
 (0)