From atv-starter-kit
Diagnoses ATV Starter Kit installation health across project scaffold, Copilot CLI marketplace plugins, and VS Code AgentPlugins. Checks install scope, version drift, git state, file integrity, hooks, MCP prereqs, dependencies.
npx claudepluginhub all-the-vibes/atv-starterkit --plugin atv-starter-kitThis skill uses the workspace's default tool permissions.
Diagnose your ATV Starter Kit installation. Checks project scaffold via `atv init`, Copilot CLI marketplace plugins via `copilot plugin install`, and VS Code source-installed AgentPlugins via `Chat: Install Plugin from source`. Reports version drift, AgentPlugin git state, file integrity, hook validity, MCP prereqs, and optional dependency status.
Updates ATV Starter Kit: Copilot CLI marketplace plugins via `copilot plugin update`, VS Code source AgentPlugins via git fast-forward with confirmation, project scaffold advice. Dry-run or apply modes.
Analyzes Agent Alchemy plugin ecosystem for dependency issues, broken paths, orphaned components, and documentation drift. Produces interactive severity-ranked health reports.
Bootstraps agentic dev environment from agent.toml: validates required env vars/commands/runtimes, configures Claude Code plugins/MCP servers. Use for new repos, misconfigs, or new machines.
Share bugs, ideas, or general feedback.
Diagnose your ATV Starter Kit installation. Checks project scaffold via atv init, Copilot CLI marketplace plugins via copilot plugin install, and VS Code source-installed AgentPlugins via Chat: Install Plugin from source. Reports version drift, AgentPlugin git state, file integrity, hook validity, MCP prereqs, and optional dependency status.
#$ARGUMENTS
Mode detection: Check if arguments contain fix (case-insensitive) → fix mode. Otherwise → report mode (default).
Phase 1: Detect install scope → repo-artifact + marketplace + VS Code AgentPlugin roots
Phase 2: Version check → installed vs latest npm / source git state
Phase 3: Source AgentPlugin health → owner/repo, path, commit, version metadata, divergence
Phase 4: File integrity (project) → manifest checksum verification (when manifest exists)
Phase 5: Hook validity (project) → JSON parse + script existence
Phase 6: MCP prereqs (project) → parse inputs[] from MCP config
Phase 7: Optional dep gating → only warn for deps the user opted into
Phase 8: Output graded report
Phase 9: Fix mode (opt-in, marketplace plugins only)
Use Bash and read_file to determine which install paths are present. Detection is repo-artifact-based, not manifest-based — auto-mode atv init does not write .atv/install-manifest.json, so the manifest is treated as optional metadata.
Set these flags from the working directory's repo root (or ~/.copilot/ for marketplace):
| Flag | Detection |
|---|---|
hasProject | true if any of these exist: .github/skills/ (directory), .github/copilot-instructions.md, .github/copilot-mcp-config.json, .github/hooks/copilot-hooks.json |
hasManifest | true if .atv/install-manifest.json exists (used to enable Phases 3 & 5; not gating) |
hasMarketplace | true if ~/.copilot/installed-plugins/atv-starter-kit/ exists OR copilot plugin marketplace list mentions atv-starter-kit |
hasSourceAgentPlugins | true if 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> |
On Windows, $HOME may resolve through Git Bash and %USERPROFILE% may be clearer in PowerShell. Probe both Stable and Insiders roots without hardcoding a machine-specific username:
| Product | Root examples |
|---|---|
| VS Code Stable | $HOME/.vscode/agent-plugins/github.com, %USERPROFILE%\.vscode\agent-plugins\github.com |
| VS Code Insiders | $HOME/.vscode-insiders/agent-plugins/github.com, %USERPROFILE%\.vscode-insiders\agent-plugins\github.com |
If !hasProject && !hasMarketplace && !hasSourceAgentPlugins: print "No ATV install detected. To install: npx atv-starterkit init (project scaffold), copilot plugin marketplace add All-The-Vibes/ATV-StarterKit && copilot plugin install atv-everything@atv-starter-kit (marketplace), or VS Code Chat: Install Plugin from source with All-The-Vibes/ATV-StarterKit." and stop.
Record what was detected for the report header.
For each detected scope, determine the installed version and compare to the latest npm release.
npm view atv-starterkit version 2>/dev/null
If the call fails (offline, registry down), record "latest: unknown" and proceed — version comparison becomes informational.
If hasManifest: read .atv/install-manifest.json and extract the catalogVersion string field:
node -e "console.log(JSON.parse(require('fs').readFileSync('.atv/install-manifest.json','utf8')).catalogVersion || 'unknown')"
If hasProject && !hasManifest: report "project install detected but no manifest. Auto-mode atv init does not write a manifest. Re-run atv init --guided to opt into manifest-tracked state." Don't fail — this is informational.
Walk ~/.copilot/installed-plugins/atv-starter-kit/ directly (more robust than parsing copilot plugin list text output). For each subdirectory containing a plugin.json, read its name and version fields:
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 + '@' + (p.version || 'unknown'))"
fi
done
For each installed version, compare to latest. Use semver-aware comparison if possible; otherwise string compare and flag any difference as 🟡 with the suggestion to run /atv-update.
If hasSourceAgentPlugins, inspect each discovered checkout under the VS Code AgentPlugin roots. Include ATV and other GitHub-source AgentPlugins such as Compound Engineering in the report, because stale source installs are easiest to diagnose when the actual installed directory is inspected.
For each plugin directory:
owner/repo from the github.com/<owner>/<repo> path segments.package.json versionVERSION.claude-plugin/plugin.json versionplugin.json versiongit describe --tags --always when availableorigin URL when availablegit status --shortDo not mutate source AgentPlugin checkouts in /atv-doctor. This phase is read-only except for best-effort git remote metadata fetch.
Summarize source-installed AgentPlugins separately from Copilot CLI marketplace plugins.
Suggested report shape:
**VS Code source-installed AgentPlugins:**
- All-The-Vibes/ATV-StarterKit
- Path: <exact installed path>
- Version: 2.6.3 (from VERSION)
- Git: main @ b2a2d11 (v2.6.3)
- Remote: origin/main, clean, behind by 0 / ahead by 0 🟢
- EveryInc/compound-engineering-plugin
- Path: <exact installed path>
- Version: 3.2.0 (from package.json)
- Git: main @ <commit> (<describe>)
- Remote: origin/main, behind by N 🟡 update available
Severity rules:
| State | Severity | Meaning |
|---|---|---|
| clean and aligned with upstream | 🟢 ok | Source plugin checkout appears current |
| clean and behind upstream | 🟡 warn | Update available; run /atv-update |
| dirty worktree | 🟡 warn | Local edits present; update must not overwrite silently |
| ahead of upstream | 🟡 warn | Local commits present; update needs manual review |
| diverged from upstream | 🔴 critical | Both local and remote changed; do not auto-update |
| detached HEAD or no upstream | ⚪ info | Version can be reported, but update path is manual |
| missing version metadata | ⚪ info | Git state is still useful; version is unknown |
Skip this phase entirely when !hasManifest and emit:
⚪ Integrity check requires a manifest. Auto-mode
atv initdoes not write one. Runatv init --guidednext time to enable checksum-based integrity verification.
When hasManifest, read .atv/install-manifest.json and iterate the fileChecksums map (key = repo-relative path, value = SHA-256). For each entry:
# Compute current SHA-256 (cross-platform: prefer node)
node -e "const c=require('crypto'),fs=require('fs'); console.log(c.createHash('sha256').update(fs.readFileSync(process.argv[1])).digest('hex'))" <path>
| Comparison | Severity | Meaning |
|---|---|---|
| File missing | 🔴 critical | Scaffold file expected but absent |
| Checksum matches | 🟢 ok | Unmodified — would be safely overwritten by a future installer refresh |
| Checksum differs | ⚪ info | User-modified — atv init would preserve this file |
Group findings by severity in the final report (don't print one line per file unless asked).
Skip when !hasProject or .github/hooks/copilot-hooks.json is absent.
.github/hooks/copilot-hooks.json as JSON. If parse fails: 🔴 with the parse error and the file path..github/hooks/scripts/. If any referenced script is missing: 🔴 with the missing path and the hook key that references it.Skip when !hasProject or .github/copilot-mcp-config.json is absent.
Parse the MCP config:
inputs array (if present). Each entry typically looks like { "id": "github_pat", "type": "promptString", "description": "..." }. List the input IDs that any server depends on.servers, scan its env block for ${input:foo} references. Build a list of which inputs are required by which servers.MCP servers configured:
- github (requires input: github_pat)
- azure (uses Azure CLI auth)
- terraform (no auth required)
- context7 (uses default API key)
Do NOT hardcode env var names. Always parse the actual config file — variable names drift between releases (github_pat vs github_token, etc.).
For each optional tool, only warn when there's evidence the user wants it. Never warn unconditionally.
| Tool | Probe | Warn only when |
|---|---|---|
bun | bun --version | requested.gstackRuntime == true in manifest, OR any gstack runtime-requiring skill exists in .github/skills/ |
agent-browser | agent-browser --version | requested.includeAgentBrowser == true in manifest, OR .github/skills/agent-browser/ exists |
gh | gh --version | MCP config references the github server |
az | az --version | MCP config references the azure server |
node | node --version | always check (required for ATV usage) |
When !hasManifest, fall back to ⚪ informational status for everything optional ("might be needed depending on which features you use") rather than 🟡 warnings.
Print a graded report. Use this skeleton:
## 🩺 ATV Doctor Report
**Detected:**
- Project scaffold: ✓ (manifest: yes/no)
- Marketplace plugins: ✓ (N installed)
- Source AgentPlugins: ✓ (N detected)
**Versions:**
- Latest on npm: 2.6.3
- Project (catalogVersion): 2.6.2 🟡 update available
- atv-skill-autoresearch: 2.6.2 🟡 update available
- atv-pack-planning: 2.6.3 🟢 up to date
### 🔴 Critical
- ...
### 🟡 Warn
- ...
### 🟢 OK
- ...
### ⚪ Info
- ...
**Next steps:**
- Run `/atv-update` to update marketplace plugins or clean source-installed ATV checkouts.
- Project scaffold updates require manual review (today's installer is additive-only).
If zero non-info findings: "Your ATV install looks healthy! 🩺"
Only runs when mode=fix. Limited scope today — only Copilot CLI marketplace plugin updates are auto-fixable from doctor mode. Project scaffold "fixes" require the user to manually re-run the installer because today's atv init is additive-only and would not refresh existing files. Source AgentPlugin updates belong in /atv-update, where the workflow can inspect git state and ask for explicit confirmation before changing a checkout.
For each stale marketplace plugin:
AskUserQuestion:
Update
<plugin-name>from v to v? (y/n)
copilot plugin update <plugin-name>After all fixes, print a summary: "Updated N plugins, skipped M."
Constraints:
atv init (today's installer is additive-only — would not actually refresh files)./atv-doctor./atv-update).npx atv-starterkit uninstall for full removal.