PromptWorks/docs/implementationplans/2026-09-02-promptworks-mirror.md

# PromptWorks Mirror Implementation Plan

> **For agentic workers:** Use the subagent-driven-development skill (recommended) or the executing-plans skill to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Create a private, safe Git mirror of custom Microsoft Scout skills and prove a LocalSystem scheduled sync can commit and push it.
**Architecture:** `sync-skills.ps1` builds an allowlisted staging tree from the Scout custom-skill source, replaces only mirrored skill folders, regenerates the README, and commits and pushes changes. Windows Task Scheduler invokes this script as LocalSystem each Sunday at 10:00 AM; Git obtains the repository-scoped HTTPS deploy token from LocalSystem's credential store.
**Tech Stack:** PowerShell 7/Windows PowerShell, Git for Windows, Windows Task Scheduler, Windows Credential Manager, HTTPS Git remote.

## Global Constraints

- Use source `C:\Users\dkucinski\.scout\m-skills` and destination `D:\Repos\PromptWorks`.
- Set `origin` to `https://git.wucinski.duckdns.org/Daniel/PromptWorks.git`.
- Mirror each source skill directory, retaining `SKILL.md` and normal source artifacts, while excluding `node_modules`, `.git`, `.pw-profile*`, `.token-cache.json`, logs, caches, and `skills-metadata.json`.
- Do not store secrets in repository files, task arguments, environment variables, logs, or Git history.
- Append timestamped run details to `logs\sync.log`; ignore `logs\` in Git.
- Schedule `PromptWorks Weekly Skill Sync` for Sundays at 10:00 AM Pacific as `LocalSystem`, whether or not a user is logged on.
- A manual no-op run must create neither a new commit nor a push.
---

### Task 1: Create the safe skill mirror

**Files:**
- Create: `.gitignore`
- Create: `sync-skills.ps1`
- Create: `README.md`
- Modify: `docs\plans\2026-09-02-promptworks-design.md`

**Interfaces:**
- Consumes: source root passed to `sync-skills.ps1` as `-SourceRoot`, defaulting to the global source path.
- Produces: mirrored skill folders, an auto-generated `README.md`, `logs\sync.log`, and exit code `0` on success or nonzero on failure.

- [ ] Step 1: Initialize the repository and configure its remote.

  ```powershell
  Set-Location D:\Repos\PromptWorks
  git init --initial-branch main
  git remote add origin https://git.wucinski.duckdns.org/Daniel/PromptWorks.git
  git config user.name "Daniel Kucinski"
  git config user.email "dkucinski@users.noreply.github.com"
  ```

- [ ] Step 2: Add the ignore policy.

  ```gitignore
  logs/
  node_modules/
  .pw-profile*/
  .token-cache.json
  *.log
  ```

- [ ] Step 3: Implement `sync-skills.ps1` with an allowlist (`SKILL.md`, `.ps1`, `.mjs`, `.js`, `.json`, `.gitignore`) and exclusion checks for the global constraints. Make it:

  ```powershell
  [CmdletBinding()]
  param(
      [string] $SourceRoot = 'C:\Users\dkucinski\.scout\m-skills',
      [string] $RepositoryRoot = $PSScriptRoot
  )

  $ErrorActionPreference = 'Stop'
  # Write timestamped log lines to Join-Path $RepositoryRoot 'logs\sync.log'.
  # Mirror source skill directories into a temporary staging directory, then replace
  # only destination skill directories so docs and sync infrastructure remain intact.
  # Regenerate README.md from the SKILL.md frontmatter/title and first description.
  # Stage all changes; exit 0 when git status --porcelain is empty.
  # Otherwise commit with "chore: sync Scout skills <yyyy-MM-dd>" and git push origin main.
  ```

- [ ] Step 4: Run the script interactively and inspect its result.

  ```powershell
  & D:\Repos\PromptWorks\sync-skills.ps1
  git -C D:\Repos\PromptWorks status --short
  ```

  Expected result: all custom skills and their approved helpers are present, generated files are absent, the README has every skill, and the status is clean after the initial commit and push.

- [ ] Step 5: Run the no-op test.

  ```powershell
  $before = git -C D:\Repos\PromptWorks rev-parse HEAD
  & D:\Repos\PromptWorks\sync-skills.ps1
  $after = git -C D:\Repos\PromptWorks rev-parse HEAD
  if ($before -ne $after) { throw 'No-op sync created a commit.' }
  ```

  Expected result: no exception and a new success entry in `logs\sync.log`.

- [ ] Step 6: Commit the infrastructure.

  ```powershell
  git -C D:\Repos\PromptWorks add --all
  git -C D:\Repos\PromptWorks commit -m "chore: add Scout skills mirror"
  git -C D:\Repos\PromptWorks push -u origin main
  ```

### Task 2: Configure and prove the unattended system task

**Files:**
- Create: `install-system-sync-task.ps1`
- Modify: `sync-skills.ps1`
- Modify: `.gitignore`

**Interfaces:**
- Consumes: an administrator-provisioned PromptWorks-only deploy token held in LocalSystem's Credential Manager for `git.wucinski.duckdns.org`.
- Produces: a task named `PromptWorks Weekly Skill Sync` and a successful LocalSystem manual invocation.

- [ ] Step 1: Confirm the Git server accepts a write-scoped PromptWorks deploy token and provision it in LocalSystem's Windows Credential Manager without embedding it in files or command arguments.

  Expected result: `git push` from a LocalSystem context can authenticate to the specified origin, and no token appears in `sync.log` or `git config --list --show-origin`.

- [ ] Step 2: Implement `install-system-sync-task.ps1` to register the task:

  ```powershell
  $action = New-ScheduledTaskAction -Execute 'powershell.exe' -Argument '-NoProfile -ExecutionPolicy Bypass -File "D:\Repos\PromptWorks\sync-skills.ps1"'
  $trigger = New-ScheduledTaskTrigger -Weekly -DaysOfWeek Sunday -At 10:00AM
  $principal = New-ScheduledTaskPrincipal -UserId 'SYSTEM' -LogonType ServiceAccount -RunLevel Highest
  $settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Hours 1)
  Register-ScheduledTask -TaskName 'PromptWorks Weekly Skill Sync' -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Description 'Mirrors custom Microsoft Scout skills to PromptWorks.' -Force
  ```

- [ ] Step 3: Register the task from an elevated PowerShell session and inspect it.

  ```powershell
  & D:\Repos\PromptWorks\install-system-sync-task.ps1
  Get-ScheduledTask -TaskName 'PromptWorks Weekly Skill Sync' | Select-Object TaskName, State, Principal
  ```

  Expected result: task name is `PromptWorks Weekly Skill Sync`; principal user ID is `SYSTEM`; task state is `Ready`.

- [ ] Step 4: Force the system task to run and inspect its recorded outcome.

  ```powershell
  Start-ScheduledTask -TaskName 'PromptWorks Weekly Skill Sync'
  Start-Sleep -Seconds 15
  Get-ScheduledTaskInfo -TaskName 'PromptWorks Weekly Skill Sync' | Select-Object LastRunTime, LastTaskResult
  Get-Content D:\Repos\PromptWorks\logs\sync.log -Tail 30
  ```

  Expected result: `LastTaskResult` is `0`, the log records a successful mirror/no-op, and the remote branch contains the initial mirror commit.

- [ ] Step 5: Commit the task installer.

  ```powershell
  git -C D:\Repos\PromptWorks add install-system-sync-task.ps1 sync-skills.ps1 .gitignore
  git -C D:\Repos\PromptWorks commit -m "chore: schedule system skill sync"
  git -C D:\Repos\PromptWorks push
  ```

## Spec Coverage Review

The plan covers private origin configuration, per-skill folders, safe source artifacts, generated root index, ignored local logging, weekly Sunday scheduling, LocalSystem execution, deploy-token isolation, initial push, and no-op/task execution proof.