| name | atv-update |
| description | Update ATV Starter Kit to the latest version. Handles Copilot CLI marketplace plugins, VS Code source-installed AgentPlugins, and project scaffold advisory status. Marketplace plugins use `copilot plugin update` with confirmation. Clean source AgentPlugins can fast-forward with confirmation. Project scaffold remains advisory because today's installer is additive-only. Triggers on 'atv update', 'update atv', 'upgrade atv', 'atv upgrade', 'refresh atv', 'atv latest'. |
| argument-hint | [mode: dry-run | apply (default)] |
/atv-update — Update ATV Starter Kit
Bring your ATV install up to the latest version. Handles three install paths:
- Marketplace plugins — auto-updated via
copilot plugin update (with per-plugin confirmation).
- VS Code source-installed AgentPlugins — updated only when the checkout is clean and can fast-forward safely (with confirmation and reload guidance).
- Project scaffold — advisory only. Today's installer is
additive-only and npx atv-starterkit@latest init will NOT refresh existing scaffold files. This skill prints the version delta and the exact commands you can run yourself.
Future: Once the installer gains a --refresh flag (read manifest → overwrite checksum-clean files → preserve drifted files), this skill will gain auto-update for project scaffold too. Tracked as a known gap.
Arguments
#$ARGUMENTS
Mode detection: Check if arguments contain dry-run or dry (case-insensitive) → dry-run mode. Otherwise → apply mode (default).
Execution Flow
Phase 1: Detect install scope → same as /atv-doctor Phase 1
Phase 2: Read installed versions → project + marketplace + source AgentPlugins
Phase 3: Fetch latest npm version → npm view
Phase 4: Show changelog (best-effort) → fetch + parse, fall back to link
Phase 5: Plan update → structured table of components + commands
Phase 6: Apply marketplace updates → copilot plugin update with confirmation
Phase 7: Apply source plugin updates → clean fast-forward only, with confirmation
Phase 8: Verify and reload guidance → suggest /atv-doctor + VS Code reload/restart
Phase 1: Detect install scope
Same detection logic as /atv-doctor Phase 1 — repo-artifact-based, not manifest-only:
| Flag | Detection |
|---|
hasProject | any of .github/skills/, .github/copilot-instructions.md, .github/copilot-mcp-config.json exists |
hasManifest | .atv/install-manifest.json exists |
hasMarketplace | ~/.copilot/installed-plugins/atv-starter-kit/ exists |
hasSourceAgentPlugins | any git checkout exists under a VS Code AgentPlugin root such as $HOME/.vscode/agent-plugins/github.com/<owner>/<repo> or $HOME/.vscode-insiders/agent-plugins/github.com/<owner>/<repo> |
Probe both Stable and Insiders roots. On Windows, prefer profile-aware paths such as %USERPROFILE%\.vscode-insiders\agent-plugins\github.com in PowerShell and $HOME/.vscode-insiders/agent-plugins/github.com in Bash; never hardcode a machine-specific user directory.
If !hasProject && !hasMarketplace && !hasSourceAgentPlugins: print "No ATV install detected. Nothing to update. Run npx atv-starterkit init to scaffold, copilot plugin marketplace add All-The-Vibes/ATV-StarterKit to register the marketplace, or VS Code Chat: Install Plugin from source with All-The-Vibes/ATV-StarterKit." and stop.
Phase 2: Read installed versions
Project (when hasProject && hasManifest)
node -e "console.log(JSON.parse(require('fs').readFileSync('.atv/install-manifest.json','utf8')).catalogVersion || 'unknown')"
When hasProject && !hasManifest: project version is unknown (auto-mode doesn't write a manifest). Note this and continue — /atv-update will still recommend running the installer.
Marketplace plugins
Walk ~/.copilot/installed-plugins/atv-starter-kit/ directly. For each subdirectory with a plugin.json, read name and version:
for dir in ~/.copilot/installed-plugins/atv-starter-kit/*/; do
if [ -f "$dir/plugin.json" ]; then
node -e "const p = require('$dir/plugin.json'); console.log(p.name + '\t' + (p.version || 'unknown'))"
fi
done
Build a list {name, currentVersion} for each ATV plugin.
VS Code source-installed AgentPlugins
Walk VS Code Stable and Insiders AgentPlugin roots under agent-plugins/github.com/<owner>/<repo>. By default, target only All-The-Vibes/ATV-StarterKit and datorresb/ATV-StarterKit source installs. If the user explicitly named another owner/repo or exact plugin path in the arguments, inspect that target too.
For each target checkout, collect:
- exact path
- owner/repo from the path
- version metadata from
package.json, VERSION, .claude-plugin/plugin.json, or plugin.json
- current branch or detached HEAD
- current commit and
git describe --tags --always when available
- origin URL
- dirty state from
git status --short
- upstream tracking branch and ahead/behind counts after best-effort fetch
Classify source plugin update state:
| State | Update action |
|---|
| clean, tracking branch, behind remote only | eligible for fast-forward after confirmation |
| clean and aligned | no update needed |
| dirty worktree | stop; explain local edits must be reviewed first |
| ahead of remote | stop; explain local commits must be reviewed first |
| diverged | stop; explain both local and remote changed |
| detached HEAD or no upstream | stop; manual update path only |
| fetch failed | stop; remote state unknown |
Do not run git reset, git stash, branch checkout, folder deletion, or reclone as part of normal update.
Phase 3: Fetch latest npm version
LATEST=$(npm view atv-starterkit version 2>/dev/null)
All ATV plugins share the kit's release cadence — the latest plugin version equals the latest npm version. If the call fails: print "Could not reach the npm registry. Skipping update plan." and stop.
Phase 4: Show changelog (best-effort)
Always print the version numbers regardless of network state:
ATV Starter Kit
Latest: <LATEST>
Project: <PROJECT_VERSION or "unknown">
Plugins: N installed (mixed versions: <list>)
Then attempt to fetch the changelog snippet:
curl -fsSL https://raw.githubusercontent.com/All-The-Vibes/ATV-StarterKit/main/CHANGELOG.md 2>/dev/null
If the fetch succeeds, attempt to extract the section between the heading for the current version and the heading for the latest version (heading format ## [X.Y.Z] — YYYY-MM-DD). Print up to ~80 lines of that excerpt.
If the fetch or parse fails, just print:
See https://github.com/All-The-Vibes/ATV-StarterKit/blob/main/CHANGELOG.md for what's new.
This is best-effort — never block the rest of the flow on changelog availability.
Phase 5: Plan update
Build a structured plan and print it. Two sections:
Project scaffold (advisory only)
If hasProject and project version is behind the latest, print:
📋 Project scaffold update (manual)
The installer is currently additive-only. `npx atv-starterkit@latest init`
will NOT refresh existing scaffold files. To update your project scaffold,
choose one approach:
Option A — Review and apply selectively (preserves customizations):
• Visit https://github.com/All-The-Vibes/ATV-StarterKit
• Diff the templates against your .github/ files
• Apply changes that matter to you
Option B — Clean reinstall (loses local edits to ATV files):
npx atv-starterkit@latest uninstall
npx atv-starterkit@latest init # or `init --guided`
Option C — Wait for installer refresh support (tracked as a known gap)
If hasProject but project version equals the latest: print "Project scaffold is up to date." and skip Options.
Marketplace plugins (auto)
For each plugin from Phase 2 that's behind LATEST, list it as:
🔄 Marketplace updates available (Phase 6 will run these):
• copilot plugin update <name> (current: vX.Y.Z → latest: vA.B.C)
• ...
If all plugins are up to date: print "All marketplace plugins are up to date."
VS Code source-installed AgentPlugins (auto only when safe)
For each detected ATV source plugin:
🔄 Source AgentPlugin updates
• All-The-Vibes/ATV-StarterKit
Path: <exact path>
State: clean, main behind origin/main by N commits
Action: eligible for fast-forward in Phase 7
For blocked states, print the exact reason and do not include an automatic command in the apply plan:
⚠️ Source AgentPlugin requires manual review
• EveryInc/compound-engineering-plugin
Path: <exact path>
State: dirty worktree
Action: skipped — local edits would be overwritten by an update
If a reinstall/removal is the only practical remediation, present it as a separate destructive option, not as the default update path. It must show the exact folder that would be removed and require explicit confirmation before removal.
Phase 6: Apply marketplace updates
Skip this phase entirely in dry-run mode.
Project scaffold updates are NEVER auto-applied — see Phase 5 rationale. Source AgentPlugin updates are handled in Phase 7.
For each marketplace plugin from Phase 5 that's behind:
- Use
AskUserQuestion:
Update <plugin-name> from v to v now? (y/n)
- On
y: run copilot plugin update <plugin-name>. Capture output.
- On
n: skip and continue.
- On error: report the failure clearly and continue with the next plugin.
After the loop, print a summary:
Updated N marketplace plugins.
Skipped M.
Errored on X (see above for details).
Phase 7: Apply source plugin updates
Skip this phase entirely in dry-run mode.
For each source AgentPlugin classified as clean and behind-only:
- Show the exact owner/repo, installed path, current commit, upstream branch, and behind count.
- Use
AskUserQuestion:
Fast-forward source AgentPlugin <owner>/<repo> at <exact path> now? (y/n)
- On
y: run a fast-forward-only update in that plugin directory.
- On
n: skip and continue.
- On error: report the failure clearly and do not try destructive remediation automatically.
For blocked states:
- Dirty worktree: print the changed-file summary and stop. Do not stash, reset, or overwrite.
- Ahead or diverged: print ahead/behind counts and stop. The user must review local commits before update.
- Detached HEAD or no upstream: print that no safe automatic update target exists.
- Fetch failed: print that remote state is unknown and stop.
Destructive reinstall/removal fallback
Only offer this after a clean in-place update is impossible or has failed, and only when the user asks to remediate.
Before removal:
- Print exactly what would be lost: the full plugin folder path and all files inside it.
- Ask for explicit confirmation naming that exact folder.
- Remove only that plugin folder after confirmation.
- Verify the folder and its metadata file are gone.
- Tell the user to reinstall through VS Code
Chat: Install Plugin from source.
Never remove an entire agent-plugins, github.com, .vscode, or .vscode-insiders directory.
Phase 8: Verify and reload guidance
After applying any changes, suggest:
Run /atv-doctor to verify the post-update install state.
If any source AgentPlugin was updated or reinstalled, also print:
Reload or restart VS Code / VS Code Insiders so the AgentPlugin content is reloaded. If the old skills still appear, close all VS Code windows and reopen the workspace before re-running /atv-doctor.
Don't run /atv-doctor or reload VS Code automatically — let the user choose.
What this skill does NOT do
- Auto-refresh project scaffold files (installer limitation; tracked as future work).
- Force-update dirty, ahead, diverged, detached, or untracked source AgentPlugin checkouts.
- Silently delete or reinstall VS Code AgentPlugin folders.
- Update gstack — that's
gstack's own responsibility (gstack syncs from its source repo).
- Update agent-browser —
npm install -g agent-browser is manual.
- Pin specific versions —
copilot plugin install plugin@marketplace doesn't accept a version. All ATV plugins share the kit version.
- Roll back to a previous version —
copilot plugin uninstall then install to a specific tag is the manual path.
