Copilot instructions

1# Copilot Instructions
2 
3This repository contains PowerShell scripts that sync Copilot resources from [github/awesome-copilot](https://github.com/github/awesome-copilot) to a local machine and distribute them to the right VS Code/Copilot locations.
4 
5## Script Workflow
6 
7Scripts are designed to be run in this order:
8 
9```text
10configure.ps1                      # Main entry point (chains all steps)
11scripts/sync-awesome-copilot.ps1   # 1. Clone/pull github/awesome-copilot → ~/.awesome-copilot/
12scripts/init-user.ps1              # 2. User-level resources → prompts\ and ~/.copilot/skills/
13scripts/init-repo.ps1              # 3. Interactive per-repo setup → .github/
14```
15 
16**Resource scopes:**
17 
18- **User-level** (all VS Code sessions, no .github/ needed): Agents + Instructions → `%APPDATA%\Code\User\prompts\`; Skills → `~/.copilot/skills/`
19- **Per-repo** (committed to `.github/`): Agents, Instructions, Hooks, Workflows, Skills
20 
21## Key Conventions
22 
23### Error Handling
24 
25All scripts use `$ErrorActionPreference = 'Stop'` so errors terminate rather than prompt. Use `try/catch` blocks for recoverable errors — do not rely on error preference for expected failure paths.
26 
27### Logging
28 
29Use the `Log` / `Write-Log` function (not `Write-Host` directly):
30 
31```powershell
32Log "Message here"           # INFO (Cyan)
33Log "Something wrong" 'WARN' # Yellow
34Log "Done!" 'SUCCESS'        # Green
35Log "Failed" 'ERROR'         # Red
36```
37 
38### Dry-Run Pattern
39 
40Every destructive operation must be guarded by `$DryRun`:
41 
42```powershell
43if ($DryRun) { Log "[DryRun] Would do X"; return 'would-copy' }
44# actual operation here
45```
46 
47### Change Detection
48 
49Always use SHA256 hash comparison before copying — never overwrite blindly:
50 
51```powershell
52$srcHash = (Get-FileHash $Src -Algorithm SHA256).Hash
53$dstHash = if (Test-Path $dest) { (Get-FileHash $dest -Algorithm SHA256).Hash } else { $null }
54if ($srcHash -eq $dstHash) { return 'unchanged' }
55```
56 
57### Portable Paths
58 
59Always use `$HOME`, `$env:APPDATA`, and `Join-Path` — never hardcode user paths:
60 
61```powershell
62# ✅
63$cacheDir = Join-Path $HOME '.awesome-copilot'
64# ❌
65$cacheDir = 'C:\Users\Someone\.awesome-copilot'
66```
67 
68### Parameter Patterns
69 
70- `-DryRun` / `-Plan` — preview without writing
71- `-Skip*` switches (e.g. `-SkipAgents`, `-SkipHooks`) — granular opt-out
72- Comma-separated strings for lists: `[string]$Categories = 'agents,hooks,instructions,skills,workflows'`
73- Default paths always use `$HOME` or `$env:APPDATA`
74 
75## External Dependencies
76 
77- **`gh` (GitHub CLI)**: preferred tool for cloning/pulling `github/awesome-copilot`; handles authentication automatically via `gh auth login`. Falls back to `git` if `gh` is not available.
78- **`Out-GridView`**: used in `init-repo.ps1` and `init-user.ps1` for interactive picking; automatically falls back to a numbered console menu if unavailable.
79 
80## Local Cache Structure
81 
82`sync-awesome-copilot.ps1` writes to `~/.awesome-copilot/` (a sparse git clone):
83 
84```text
85~/.awesome-copilot/
86  .git/            git metadata (managed automatically)
87  agents/          *.agent.md
88  instructions/    *.instructions.md
89  workflows/       *.md
90  hooks/           <hook-name>/ (directories)
91  skills/          <skill-name>/ (directories)
92  manifest.json    file inventory with hashes (written after each sync)
93  status.txt       human-readable summary of last sync run
94```
95 
96Sync logs are written to `scripts/logs/sync-YYYYMMDD-HHMMSS.log` (always relative to the script's own directory via `$PSScriptRoot`).
97 
98## Contributing
99 
100- Update `CHANGELOG.md` with every change under the appropriate version
101- Test with `-DryRun` / `-Plan` before running live
102- Run `sync-awesome-copilot.ps1 -Plan` to verify without writing files
103- New parameters must follow the existing `[switch]$Skip*` / `[string]$Target` naming conventions
104- See `CONTRIBUTING.md` for the full PR checklist
105