feat: redesign for current awesome-copilot structure

.github/copilot-instructions.md

@@ -0,0 +1,97 @@
+# Copilot Instructions
+
+This 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.
+
+## Script Workflow
+
+Scripts are designed to be run in this order:
+
+```
+configure.ps1                      # Main entry point (chains all steps)
+scripts/sync-awesome-copilot.ps1   # 1. Clone/pull github/awesome-copilot → ~/.awesome-copilot/
+scripts/publish-global.ps1         # 2. Publish agents + skills globally
+scripts/init-repo.ps1              # 3. Interactive per-repo setup → .github/
+scripts/install-scheduled-task.ps1 # 4. Automate steps 1+2 on a schedule
+```
+
+**Resource scopes:**
+- **Global** (machine-wide): Agents → `%APPDATA%\Code\User\prompts\`; Skills → `~/.copilot/skills/`
+- **Per-repo** (committed to `.github/`): Instructions, Hooks, Workflows
+
+## Key Conventions
+
+### Error Handling
+All 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.
+
+### Logging
+Use the `Log` / `Write-Log` function (not `Write-Host` directly):
+```powershell
+Log "Message here"           # INFO (Cyan)
+Log "Something wrong" 'WARN' # Yellow
+Log "Done!" 'SUCCESS'        # Green
+Log "Failed" 'ERROR'         # Red
+```
+
+### Dry-Run Pattern
+Every destructive operation must be guarded by `$DryRun`:
+```powershell
+if ($DryRun) { Log "[DryRun] Would do X"; return 'would-copy' }
+# actual operation here
+```
+
+### Change Detection
+Always use SHA256 hash comparison before copying — never overwrite blindly:
+```powershell
+$srcHash = (Get-FileHash $Src -Algorithm SHA256).Hash
+$dstHash = if (Test-Path $dest) { (Get-FileHash $dest -Algorithm SHA256).Hash } else { $null }
+if ($srcHash -eq $dstHash) { return 'unchanged' }
+```
+
+### Portable Paths
+Always use `$HOME`, `$env:APPDATA`, and `Join-Path` — never hardcode user paths:
+```powershell
+# ✅
+$cacheDir = Join-Path $HOME '.awesome-copilot'
+# ❌
+$cacheDir = 'C:\Users\Someone\.awesome-copilot'
+```
+
+### Parameter Patterns
+- `-DryRun` / `-Plan` — preview without writing
+- `-Skip*` switches (e.g. `-SkipAgents`, `-SkipHooks`) — granular opt-out
+- Comma-separated strings for lists: `[string]$Categories = 'agents,instructions,workflows,hooks,skills'`
+- Default paths always use `$HOME` or `$env:APPDATA`
+
+## External Dependencies
+
+- **`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.
+- **`Out-GridView`**: used in `init-repo.ps1` for interactive picking; automatically falls back to a numbered console menu if unavailable.
+
+## Local Cache Structure
+
+`sync-awesome-copilot.ps1` writes to `~/.awesome-copilot/` (a sparse git clone):
+```
+~/.awesome-copilot/
+  .git/            git metadata (managed automatically)
+  agents/          *.agent.md
+  instructions/    *.instructions.md
+  workflows/       *.md
+  hooks/           <hook-name>/ (directories)
+  skills/          <skill-name>/ (directories)
+  manifest.json    file inventory with hashes (written after each sync)
+  status.txt       human-readable summary of last sync run
+```
+
+Sync logs are written to a `logs/` folder in the working directory where the script was invoked (typically the repo root when run via `configure.ps1`).
+
+## Scheduled Task
+
+`configure.ps1 -InstallTask` chains `sync-awesome-copilot.ps1 → publish-global.ps1` and registers a Windows Scheduled Task named `AwesomeCopilotSync` (delegating to `scripts/install-scheduled-task.ps1`). The task runs under the current user context — the user must be logged in for it to execute.
+
+## Contributing
+
+- Update `CHANGELOG.md` with every change under the appropriate version
+- Test with `-DryRun` / `-Plan` before running live
+- Run `sync-awesome-copilot.ps1 -Plan` to verify without writing files
+- New parameters must follow the existing `[switch]$Skip*` / `[string]$Target` naming conventions
+- See `CONTRIBUTING.md` for the full PR checklist

.gitignore

@@ -1,9 +1,6 @@
 # Logs directory (contains sync operation logs)
 logs/
 
-# Local awesome-copilot cache (user-specific)
-.awesome-copilot/
-
 # PowerShell history
 .history
 
@@ -14,4 +11,24 @@ logs/
 Thumbs.db
 
 # macOS
-.DS_Store
+.DS_Store
+
+# Local cache (managed by sync-awesome-copilot.ps1 - not committed)
+.awesome-copilot/
+
+# Temp files from PowerShell / editors
+*.tmp
+*.bak
+~$*
+
+# Per-repo Copilot resources installed from github/awesome-copilot
+# These belong to the awesome-copilot community — not ours to redistribute.
+# Commit these in YOUR projects; exclude them here (demo/tooling repo only).
+.github/agents/
+.github/hooks/
+.github/instructions/
+.github/skills/
+# Only ignore copilot agentic workflow .md files — not GitHub Actions .yml files
+.github/workflows/*.md
+# Subscription tracking manifest (local state, not redistributed)
+.github/.copilot-subscriptions.json

CHANGELOG.md

@@ -5,9 +5,110 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.2] - 2026-02-27
+
+### Changed
+
+- `configure.ps1`: use `$PSScriptRoot` to locate the `scripts/` folder (replaces `$MyInvocation.MyCommand.Path` which behaves differently when dot-sourced)
+- `scripts/sync-awesome-copilot.ps1`: replace manual SHA256 with built-in `Get-FileHash` — cleaner and avoids loading entire file into memory
+- `scripts/publish-global.ps1`: emit a `WARN` log when VS Code `settings.json` is not found (was a silent no-op); user is directed to open VS Code once to generate the file
+
+## [1.2.1] - 2026-02-27
+
+### Fixed
+
+- `configure.ps1`: `-InstallTask` / `-UninstallTask` now automatically skip the `init-repo` prompt (validation moved before Step 1 so the flag takes effect)
+- `configure.ps1`: prompts to overwrite when the scheduled task already exists, instead of throwing a hard error
+- `scripts/install-scheduled-task.ps1`: added `-WorkingDirectory` to both scheduled task actions (was defaulting to `C:\Windows\System32`, causing a permissions error creating the `logs/` directory)
+- `scripts/sync-awesome-copilot.ps1`: replaced relative `logs/` path with `$PSScriptRoot/logs/` so logs always land in `scripts/logs/` regardless of working directory
+- `scripts/install-scheduled-task.ps1`: updated task description (removed stale "combine" wording)
+- `scripts/publish-global.ps1`: fixed named-profile example path (`agents\` → `prompts\`)
+- `README.md`: corrected default interval (6h → 4h), log paths, authentication section, and custom-repo instructions
+- `.github/copilot-instructions.md`: removed stale GitHub API / `GITHUB_TOKEN` references; updated cache structure
+
+## [1.2.0] - 2026-02-27
+
+### Changed
+
+- `scripts/sync-awesome-copilot.ps1`: **Rewritten** — replaced GitHub API + per-file HTTP download approach with `git sparse-checkout`. First run clones `github/awesome-copilot` shallowly with only the requested categories; subsequent runs run `git pull` for near-instant delta updates. Dramatically faster (single bulk transfer vs 700+ individual HTTP requests) and removes GitHub API rate-limit concerns entirely.
+  - Prefers `gh` (GitHub CLI) for automatic auth; falls back to `git`
+  - New `-GitTool auto|gh|git` parameter to override tool selection
+  - Removed parameters: `-NoDelete`, `-DiffOnly`, `-SkipBackup`, `-BackupRetention` (git handles all of these natively)
+  - Migrates automatically from the old API-based cache (renames non-git `~/.awesome-copilot/` to `~/.awesome-copilot-backup-<date>` before cloning)
+  - `manifest.json` still written (from local file scan) for backward compatibility with `publish-global.ps1` and `configure.ps1`
+
+### Added
+
+- `README.md`: document `gh`/`git` requirement; update sync section to reflect git-based approach
+
+## [1.1.2] - 2026-02-27
+
+### Added
+
+- `configure.ps1` — interactive orchestrator that chains sync → publish-global → init-repo; each step independently skippable via `-SkipSync`, `-SkipPublish`, `-SkipInit`; `-DryRun` passes through to all child scripts; shows last sync timestamp from cache manifest before running
+
+### Added
+
+- `init-repo.ps1`: added Agents as a fourth interactive category (installs to `.github/agents/`)
+- `init-repo.ps1`: `Detect-RepoStack` — auto-detects language/framework from file signals and marks relevant items with ★ in the picker
+- `init-repo.ps1`: `Prompt-RepoIntent` — interactive fallback for new/empty repos; asks language, project type, and concerns
+- `init-repo.ps1`: `-- none / skip --` sentinel row in every OGV picker so clicking OK with no intentional selection installs nothing
+- `publish-global.ps1`: auto-configures `chat.useAgentSkills` and `chat.agentSkillsLocations` in VS Code `settings.json` when skills are published
+- `.github/copilot-instructions.md`: Copilot instructions for this repository covering script workflow, conventions, and contributing guidelines
+
+### Fixed
+
+- `normalize-copilot-folders.ps1`: `Split-Path -LeafParent` → `Split-Path -Parent` (`-LeafParent` is not a valid parameter and would throw at runtime)
+- `install-scheduled-task.ps1`: removed `-Quiet` from `publish-global.ps1` invocation (`publish-global.ps1` has no `-Quiet` parameter; would throw on scheduled runs)
+- `init-repo.ps1`: `$Items.IndexOf($_)` → `[Array]::IndexOf($Items, $_)` (`System.Object[]` has no instance `IndexOf` method; affected console-menu fallback path)
+- `init-repo.ps1`: fixed OGV column name `[*] Installed` → `Installed` (special characters caused WPF binding errors at runtime)
+- `init-repo.ps1`: fixed `return if (...)` runtime error in `Install-File` — replaced with explicit `if/else` branches
+- `publish-global.ps1`: corrected agents target path to `%APPDATA%\Code\User\prompts\` (was incorrectly set to `agents\`)
+
+### Changed
+
+- `publish-global.ps1`: updated inline comment from "CCA" to "VS Code Agent mode / Copilot CLI"
+- `README.md`: corrected all `-Interval` references to `-Every`; fixed `-ProfileName` → `-ProfileRoot`/`-AllProfiles`; updated agents path to `%APPDATA%\Code\User\prompts\`; updated `init-repo.ps1` section to reflect agents category and smart detection; fixed custom `-AgentsTarget` example path
+- `.github/copilot-instructions.md`: corrected agents path from `%APPDATA%\Code\User\agents\` to `%APPDATA%\Code\User\prompts\`
+
+### Fixed
+
+- `sync-awesome-copilot.ps1`: changed `$ErrorActionPreference` from `Inquire` to `Stop` — `Inquire` caused the script to hang waiting for interactive input when run as a scheduled task
+
+### Changed
+
+- `init-repo.ps1`: removed skills from per-repo initialisation; skills are globally available via `publish-global.ps1` (`~/.copilot/skills/`) and users should reference the source directly at [github/awesome-copilot](https://github.com/github/awesome-copilot) rather than committing point-in-time copies to repos
+
+## [1.1.0] - 2026-02-26
+
+### Added
+
+- `publish-global.ps1` — publishes agents to the VS Code user agents folder (via junction so sync updates are reflected immediately) and skills to `~/.copilot/skills/`; supports `-DryRun`, `-SkipAgents`, `-SkipSkills`, `-AgentsTarget`, `-SkillsTarget`
+- `init-repo.ps1` — interactive script to initialise a repo with per-repo resources (instructions, hooks, workflows); uses Out-GridView on Windows with a numbered console-menu fallback; supports `-RepoPath`, `-DryRun`, `-SkipInstructions`, `-SkipHooks`, `-SkipWorkflows`
+
+### Changed
+
+- Updated default sync categories to match current awesome-copilot repository structure:
+  - **Added**: `agents`, `workflows`, `hooks`, `skills`
+  - **Removed**: `chatmodes`, `prompts` (no longer exist in awesome-copilot)
+- Added recursive directory traversal in `sync-awesome-copilot.ps1` to support subdirectory-based categories (`skills/`, `hooks/`, `plugins/`)
+- Extended file extension filter to include `.sh` files (required for hooks to function — each hook ships shell scripts alongside its `hooks.json`)
+- Updated `combine-and-publish-prompts.ps1` categories from `chatmodes/instructions/prompts` to `agents/instructions/workflows`; added deprecation notice at top (superseded by `publish-global.ps1` + `init-repo.ps1`); kept for backwards compatibility
+- Updated `normalize-copilot-folders.ps1` to classify `*.agent.md` → `agents/` and ensure `agents/` directory is created on normalize runs
+- Updated `install-scheduled-task.ps1`: default categories now `agents,instructions,workflows,hooks,skills`; `-IncludeCollections` replaced by `-IncludePlugins`; `-SkipCombine` replaced by `-SkipPublishGlobal`; scheduled actions now run `publish-global.ps1` after sync
+
+### Removed
+
+- `normalize-copilot-folders.ps1` — removed (legacy, superseded by junction-based agent publishing and `init-repo.ps1`)
+
+- `plugins/` and `cookbook/` are available but opt-in via `-IncludePlugins` due to their size
+- Hooks are synced as complete packages (README.md + hooks.json + .sh scripts) preserving their directory structure
+- **Design rationale**: agents and skills are global (agents available in all VS Code workspaces; skills loaded on-demand); instructions/hooks/workflows are per-repo opt-in via `init-repo.ps1` to avoid conflicts between contradicting instruction files
+
 ## [1.0.0] - 2025-10-20
 
 ### Added
+
 - Initial release of VS Code Copilot Resource Sync Scripts
 - `sync-awesome-copilot.ps1` - Sync resources from GitHub awesome-copilot repository
 - `combine-and-publish-prompts.ps1` - Combine and publish resources to VS Code
@@ -23,6 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Support for multiple VS Code profiles
 
 ### Features
+
 - Portable paths using environment variables ($HOME, $env:APPDATA)
 - Preserves user-created custom files in combined directory
 - Incremental updates (only downloads changed files)
@@ -31,6 +133,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Detailed sync logs with timestamps
 
 ### Security
+
 - No hardcoded credentials or personal information
 - Optional environment variable for GitHub token
 - All sensitive data handled via environment variables
@@ -40,6 +143,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Future Plans
 
 ### Planned Features
+
 - [ ] Configuration file support (YAML/JSON)
 - [ ] Backup and restore functionality
 - [ ] Conflict resolution UI for duplicate resources
@@ -49,12 +153,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [ ] Cross-platform support (macOS, Linux)
 
 ### Known Issues
+
 - Junction creation requires appropriate permissions on some systems
 - Scheduled task runs under user context (requires user to be logged in)
 
 ---
 
 **Note:** Version numbers follow [Semantic Versioning](https://semver.org/):
+
 - MAJOR version for incompatible API changes
 - MINOR version for new functionality in a backwards compatible manner
 - PATCH version for backwards compatible bug fixes

CONTRIBUTING.md

@@ -7,16 +7,18 @@ Thank you for considering contributing to the VS Code Copilot Resource Sync Scri
 ### Reporting Bugs
 
 If you find a bug, please create an issue with:
+
 - Clear description of the problem
 - Steps to reproduce
 - Expected vs actual behavior
 - PowerShell version (`$PSVersionTable.PSVersion`)
 - Windows version
-- Relevant log files from `$HOME\.awesome-copilot\logs\`
+- Relevant log files from `scripts\logs\`
 
 ### Suggesting Enhancements
 
 Feature requests are welcome! Please include:
+
 - Clear use case description
 - Why this feature would be useful
 - Proposed implementation (if you have ideas)
@@ -25,6 +27,7 @@ Feature requests are welcome! Please include:
 
 1. **Fork the repository**
 2. **Create a feature branch** from `main`:
+
    ```powershell
    git checkout -b feature/your-feature-name
    ```
@@ -41,20 +44,25 @@ Feature requests are welcome! Please include:
    - Add inline comments for complex code
 
 5. **Test your changes**:
+
    ```powershell
+   # Full dry run (no files written)
+   .\configure.ps1 -DryRun
+
    # Test individual scripts
-   .\sync-awesome-copilot.ps1
-   .\combine-and-publish-prompts.ps1
-   
+   .\scripts\sync-awesome-copilot.ps1 -Plan
+   .\scripts\publish-global.ps1 -DryRun
+
    # Test scheduled task installation
-   .\install-scheduled-task.ps1 -Interval "1h"
+   .\configure.ps1 -InstallTask -Every "1h"
    Start-ScheduledTask -TaskName "AwesomeCopilotSync"
-   
+
    # Verify logs
-   Get-Content "$HOME\.awesome-copilot\logs\sync-*.log" -Tail 20
+   Get-ChildItem .\scripts\logs\sync-*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 1 | Get-Content -Tail 20
    ```
 
 6. **Commit with clear messages**:
+
    ```powershell
    git commit -m "Add feature: description of what you added"
    ```
@@ -82,21 +90,21 @@ function Get-ResourceFiles {
     <#
     .SYNOPSIS
     Retrieves resource files from a directory.
-    
+
     .PARAMETER Path
     The directory path to search.
-    
+
     .PARAMETER Type
     The type of resource to filter (chatmode, instruction, prompt).
     #>
     param(
         [Parameter(Mandatory)]
         [string]$Path,
-        
+
         [ValidateSet('chatmode', 'instruction', 'prompt')]
         [string]$Type
     )
-    
+
     try {
         $pattern = "*.$Type.md"
         Get-ChildItem -Path $Path -Filter $pattern -File
@@ -145,6 +153,7 @@ Before submitting a PR, verify:
 ## Questions?
 
 Feel free to:
+
 - Open an issue for discussion
 - Ask questions in pull request comments
 - Reach out to maintainers