Skip to content

Commit 624d720

Browse files
MariusStorhaugMariusStorhaug
authored
Merge branch 'main' into dependabot/github_actions/actions/checkout-5
2 parents 22998cd + 242a0cd commit 624d720

File tree

6 files changed

+675
-3
lines changed

6 files changed

+675
-3
lines changed

‎.github/instructions/universal.instructions.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
applyTo: '**'
3+
description: Standardize and improve code with consistent formatting, structure, and clarity.
4+
---
5+
6+
## Universal Authoring Guidelines
7+
8+
- Lines MUST NOT exceed 150 characters.
9+
- Lines MUST NOT have trailing whitespace at the end of lines, including blank lines.
10+
- All files MUST end with a single newline.
11+
- Paths MUST use forward slashes (`/`), not backslashes (`\`) for compatibility across operating systems.
12+
- Files MUST use UTF-8 encoding.
13+
- Files MUST use Unix line endings (LF).

‎.github/prompts/framework/Update-Instructions.prompt.md‎

Lines changed: 317 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,317 @@
1+
---
2+
description: Comprehensive framework for generating and maintaining Copilot instruction files across repositories
3+
mode: agent
4+
model: GPT-5 (copilot)
5+
tools: []
6+
---
7+
8+
# Update Instructions Framework
9+
10+
## Overview
11+
12+
This prompt analyzes codebases and generates, updates, and maintains Copilot instruction files that guide AI coding agents. It implements a structured workflow to create a comprehensive instruction system for the PSModule ecosystem, ensuring consistent guidance across repositories while separating framework-level patterns from project-specific implementations.
13+
14+
## Specifications
15+
16+
### Target Architecture
17+
18+
The instruction system follows a two-tier hierarchy:
19+
20+
```
21+
$InstructionsPath/
22+
├── framework/ # Generic, reusable patterns (automation-managed)
23+
│ ├── main.instructions.md # Universal cross-language guidelines
24+
│ └── {Language}/ # Language-specific framework patterns
25+
│ ├── main.instructions.md
26+
│ ├── tests.instructions.md
27+
│ └── classes.instructions.md
28+
└── repo/ # Project-specific patterns (manually curated)
29+
├── main.instructions.md # Repository context and rules
30+
└── {Language}/ # Project-specific language patterns
31+
└── main.instructions.md
32+
```
33+
34+
**Path Variables** (resolved via `./scripts/Get-Paths.ps1`):
35+
- `$RepositoryPath` - Root repository path
36+
- `$InstructionsPath` - Instructions directory path (e.g., `$RepositoryPath/.github/prompts/framework`)
37+
- `$FrameworkInstructionsPath` - Framework instructions directory path (e.g., `$InstructionsPath/framework`)
38+
- `$RepositoryInstructionsPath` - Repository instructions directory path (e.g., `$InstructionsPath/repo`)
39+
40+
### Content Requirements
41+
42+
#### Framework Instructions (`$FrameworkInstructionsPath/`)
43+
44+
**Universal Cross-Language Guidelines** (`main.instructions.md`)
45+
- General style guidelines applying across all programming languages
46+
- Repository context: PSModule ecosystem patterns and structure
47+
- PSModule build process integration and tooling
48+
- Universal conventions: naming, file organization, documentation standards
49+
- Consistency guidelines for all repository files
50+
51+
**Language-Specific Technical Guidelines** (`{Language}/main.instructions.md`)
52+
- Language-specific style guidelines and best practices
53+
- Syntax conventions, formatting rules, and idiomatic patterns
54+
- Tooling integration: linters, formatters, build tools
55+
- Code quality standards and technical patterns
56+
- Error handling, logging, testing, and debugging approaches
57+
58+
#### Repository Instructions (`$RepositoryInstructionsPath/`)
59+
60+
**Project-Specific Context and Rules** (`main.instructions.md`)
61+
- Repository purpose, scope, and deliverables
62+
- Project-specific guidelines overriding/extending framework patterns
63+
- Architecture, component relationships, and integration points
64+
- Unique workflows, processes, and procedures
65+
- Target audience, use cases, and business requirements
66+
67+
**Project-Specific Language Implementation** (`{Language}/main.instructions.md`)
68+
- Language usage within this repository's specific context
69+
- Project-specific patterns, conventions, and architectural decisions
70+
- Integration patterns with other repository components
71+
- Concrete examples demonstrating the repository's approach
72+
73+
#### Content Hierarchy and Precedence
74+
1. **Framework instructions** provide foundation and universal patterns
75+
2. **Repository instructions** override and extend framework instructions
76+
3. **Language-specific instructions** inherit from their main instruction files
77+
4. **Repository language instructions** take precedence over framework language instructions
78+
79+
### Quality Standards
80+
81+
#### File Format Requirements
82+
```yaml
83+
---
84+
applyTo: <glob pattern for target files>
85+
description: <succinct purpose in one sentence>
86+
---
87+
```
88+
Content structure: Context lead, Goal, Execution steps, Behavior rules, Output format, Error handling, Definitions
89+
90+
#### Validation Criteria
91+
- All instruction files must have proper YAML frontmatter
92+
- `applyTo` patterns must correctly target intended file types
93+
- Content completeness across all discovered languages/technologies
94+
- Consistent terminology and patterns across instruction files
95+
- Proper framework vs repository categorization
96+
97+
#### Success Metrics
98+
- No content loss during migration or updates
99+
- Complete technology coverage for discovered languages
100+
- Proper separation of generic vs project-specific guidance
101+
- All legacy instruction content successfully migrated
102+
103+
## Implementation Guide
104+
105+
### Prerequisites
106+
107+
1. **Path Resolution**: Execute [Gather.ps1](scripts/Gather.ps1) to establish required path variables
108+
2. **Workspace Setup**: Ensure multiple repository scenario handling
109+
3. **Backup Strategy**: Plan rollback procedures for failed migrations
110+
111+
### Execution Workflow
112+
113+
The implementation follows five distinct phases with clear gates between each:
114+
115+
#### Phase 1: Setup (T001)
116+
- **Gate**: All paths resolved and validated
117+
- Path resolution and workspace preparation
118+
119+
#### Phase 2: Analysis (T002-T003)
120+
- **Gate**: Complete content inventory and categorization plan
121+
- Discovery and content categorization planning
122+
123+
#### Phase 3: Creation (T004-T005)
124+
- **Gate**: All instruction files created with proper structure
125+
- Framework and repository instruction file creation
126+
127+
#### Phase 4: Migration (T006)
128+
- **Gate**: All legacy content successfully migrated
129+
- Content migration from legacy sources
130+
131+
#### Phase 5: Validation (T007-T009)
132+
- **Gate**: System validated, cleaned up, and user feedback collected
133+
- Quality validation, cleanup, and final verification
134+
135+
### Task Dependencies
136+
137+
```
138+
T001 (Path Resolution)
139+
↓
140+
T002 (Discovery)
141+
↓
142+
T003 (Planning)
143+
↓
144+
T004 (Framework Creation)
145+
↓
146+
T005 (Repository Creation)
147+
↓
148+
T006 (Migration)
149+
↓
150+
T007 (Validation)
151+
↓
152+
T008 (Cleanup)
153+
↓
154+
T009 (Final)
155+
```
156+
157+
### Detailed Tasks
158+
159+
Execute tasks in the specified order, with each task depending on successful completion of previous tasks:
160+
161+
#### T001: Path Resolution
162+
- **Dependencies**: None
163+
- **Goal**: Determine repository-specific paths for consistent task execution
164+
- **Key Actions**: Run path resolution script, validate all required paths, ensure workspace compatibility
165+
- **Success Criteria**: All paths resolved and validated
166+
167+
#### T002: Discovery and Analysis
168+
- **Dependencies**: T001
169+
- **Goal**: Analyze existing instruction structure and identify content sources
170+
- **Key Actions**: Catalog existing instructions, identify languages/technologies, analyze codebase patterns
171+
- **Success Criteria**: Complete inventory of existing content and technology discovery
172+
173+
#### T003: Content Categorization and Planning
174+
- **Dependencies**: T002
175+
- **Goal**: Plan content migration and organization strategy based on specifications
176+
- **Key Actions**: Categorize content (framework vs repo-specific), identify gaps, plan file structure
177+
- **Success Criteria**: Clear categorization plan with no ambiguous content
178+
179+
#### T004: Framework Instructions Creation/Update
180+
- **Dependencies**: T003
181+
- **Goal**: Create generic, reusable instruction files according to specifications
182+
- **Key Actions**: Create universal guidelines, language-specific technical patterns, specialized components
183+
- **Success Criteria**: All framework instruction files created with proper structure and content
184+
185+
#### T005: Repository-Specific Instructions Creation/Update
186+
- **Dependencies**: T003
187+
- **Goal**: Create project-specific instruction files according to specifications
188+
- **Key Actions**: Create project context, repository-specific language patterns, specialized workflows
189+
- **Success Criteria**: All repo-specific instruction files created with project context
190+
191+
#### T006: Content Migration from Legacy Files
192+
- **Dependencies**: T004, T005
193+
- **Goal**: Migrate content from legacy sources without loss
194+
- **Key Actions**: Extract legacy content, categorize by type, migrate to appropriate instruction files
195+
- **Success Criteria**: All legacy content successfully migrated without loss
196+
197+
#### T007: Structure Validation and Quality Check
198+
- **Dependencies**: T006
199+
- **Goal**: Validate instruction system completeness and accuracy
200+
- **Key Actions**: Verify YAML frontmatter, validate file patterns, check content completeness
201+
- **Success Criteria**: All validation checks pass with no structural or content issues
202+
203+
#### T008: Legacy File Cleanup
204+
- **Dependencies**: T007
205+
- **Goal**: Clean up legacy instruction files after successful migration
206+
- **Key Actions**: Verify migration completion, remove legacy files, clean up loose files
207+
- **Success Criteria**: Legacy files cleaned up only after confirmed migration
208+
209+
#### T009: Final Validation and User Feedback
210+
- **Dependencies**: T008
211+
- **Goal**: Complete final system validation and provide user feedback
212+
- **Key Actions**: Final validation, provide completion summary, collect user feedback
213+
- **Success Criteria**: Final validation completed and user feedback provided
214+
215+
## Reference
216+
217+
### Content Templates
218+
219+
#### YAML Frontmatter Template
220+
```yaml
221+
---
222+
applyTo: "<glob pattern targeting specific file types>"
223+
description: "Brief, actionable description of the instruction's purpose"
224+
---
225+
```
226+
227+
#### Instruction File Structure
228+
```markdown
229+
# Brief Context (if needed)
230+
231+
## Goal
232+
Clear statement of what this instruction achieves.
233+
234+
## Execution Steps
235+
1. Step-by-step actions
236+
2. Ordered list format
237+
3. Specific and actionable
238+
239+
## Behavior Rules
240+
- Constraints and requirements
241+
- Quality standards
242+
- Error handling approaches
243+
244+
## Examples (if applicable)
245+
Concrete examples demonstrating the patterns.
246+
```
247+
248+
### Quick Reference
249+
250+
#### Content Categorization Matrix
251+
| Content Type | Framework | Repository |
252+
|--------------|-----------|------------|
253+
| Style guidelines | Universal patterns | Project-specific overrides |
254+
| Language patterns | Generic best practices | Repository-specific implementation |
255+
| Architecture | N/A | Project structure and components |
256+
| Build/Deploy | Generic PSModule process | Project-specific workflows |
257+
| Testing | Universal test patterns | Project-specific test strategies |
258+
259+
#### Task Execution Checklist
260+
- [ ] **T001**: Path variables established and validated
261+
- [ ] **T002**: Content inventory complete with technology identification
262+
- [ ] **T003**: Categorization plan created with clear framework/repo separation
263+
- [ ] **T004**: Framework instructions created following specifications
264+
- [ ] **T005**: Repository instructions created with project context
265+
- [ ] **T006**: Legacy content migrated without loss
266+
- [ ] **T007**: All validation checks passed
267+
- [ ] **T008**: Legacy files cleaned up safely
268+
- [ ] **T009**: User feedback collected and system verified
269+
270+
### Troubleshooting
271+
272+
#### Common Issues and Solutions
273+
274+
**Issue**: Content categorization unclear
275+
- **Solution**: Apply hierarchy: Generic patterns → framework, Project-specific patterns → repository
276+
277+
**Issue**: Legacy content migration incomplete
278+
- **Solution**: Abort cleanup, verify all content accounted for, retry migration
279+
280+
**Issue**: Validation failures
281+
- **Solution**: Check YAML frontmatter format, verify `applyTo` patterns, ensure content completeness
282+
283+
**Issue**: Path resolution fails
284+
- **Solution**: Verify `./scripts/Get-Paths.ps1` exists and executes successfully
285+
286+
#### Recovery Procedures
287+
- **Before T008**: All operations are additive, safe to retry individual tasks
288+
- **During T008**: STOP if any validation fails - content loss risk
289+
- **After T008**: Recovery requires manual restoration from version control
290+
291+
#### Abort Conditions
292+
- Path resolution script unavailable or fails
293+
- Critical content cannot be categorized (framework vs repository)
294+
- Legacy content migration would result in data loss
295+
- Validation reveals structural inconsistencies that cannot be resolved
296+
297+
### Validation Checklists
298+
299+
#### Pre-Execution Validation
300+
- [ ] Repository paths accessible and writable
301+
- [ ] Path resolution script available: `./scripts/Get-Paths.ps1`
302+
- [ ] Backup/recovery strategy in place
303+
- [ ] Multiple repository workspace scenario confirmed
304+
305+
#### Task Completion Validation
306+
- [ ] No content loss during any migration step
307+
- [ ] All instruction files have valid YAML frontmatter
308+
- [ ] `applyTo` patterns correctly target intended file types
309+
- [ ] Framework vs repository categorization follows hierarchy rules
310+
- [ ] All discovered technologies have appropriate instruction coverage
311+
312+
#### Final System Validation
313+
- [ ] Complete instruction system covers all repository needs
314+
- [ ] Legacy files removed only after confirmed migration
315+
- [ ] Framework instructions suitable for automation management
316+
- [ ] Repository instructions remain manually curated
317+
- [ ] User feedback indicates system completeness and usability

‎.github/prompts/framework/scripts/Gather.ps1‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[PSCustomObject]@{
2+
RepositoryPath = [System.IO.Path]::GetFullPath("$PSScriptRoot/../../../..")
3+
InstructionsPath = [System.IO.Path]::GetFullPath("$PSScriptRoot/../../../instructions")
4+
FrameworkInstructionsPath = [System.IO.Path]::GetFullPath("$PSScriptRoot/../../../instructions/framework")
5+
RepositoryInstructionsPath = [System.IO.Path]::GetFullPath("$PSScriptRoot/../../../instructions/repo")
6+
} | Format-List

‎README.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
1-
# Template-Docs
1+
# PSModule Documentation
22

3-
A template repo for documentation repositories
3+
This repository contains the comprehensive documentation for the PSModule development framework - a GitHub & PowerShell development framework that empowers PowerShell-savvy developers to effortlessly transform their ideas into impactful solutions.
4+
5+
## 🌟 Overview
6+
7+
PSModule provides a development framework that allows developers to focus on delivering value through their code by leveraging the GitHub platform and PowerShell to automate repetitive tasks. Whether you're a consumer or contributor, our framework enables you to concentrate on coding without distractions.
8+
9+
## 📖 Documentation Structure
10+
11+
- **[PowerShell Modules](docs/PowerShell-Modules/)** - Guidelines for module development, testing specifications, and versioning
12+
- **[GitHub Actions](docs/GitHub-Actions/)** - Best practices and implementations for CI/CD workflows
13+
- **[Solutions](docs/Solutions/)** - Real-world examples and problem-solving approaches
14+
- **[Blog](docs/Blog/)** - Latest updates, insights, and community contributions
15+
- **[About](docs/About/)** - More information about the PSModule project
16+
17+
## 🛠️ Platform Support
18+
19+
The PSModule framework prioritizes supporting the latest Long-Term Servicing (LTS) version of PowerShell to leverage the most recent features and capabilities. While we don't actively pursue Windows PowerShell 5.1 compatibility, users can still benefit from our tools by installing PowerShell 7 alongside legacy systems.
20+
21+
## 🤝 Contributing
22+
23+
We welcome contributions to improve our documentation! Please feel free to:
24+
25+
- Submit issues for documentation improvements
26+
- Create pull requests with corrections or enhancements
27+
- Share feedback on existing content

0 commit comments

Comments
 (0)