atv-doctor

/atv-doctor — ATV installation health check

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

#$ARGUMENTS

Mode detection: Check if arguments contain fix (case-insensitive) → fix mode. Otherwise → report mode (default).

Execution Flow

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)

---

Phase 1: Detect install scope

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.

---

Phase 2: Version check

For each detected scope, determine the installed version and compare to the latest npm release.

2a. Latest version (always)

npm view atv-starterkit version 2>/dev/null

If the call fails (offline, registry down), record "latest: unknown" and proceed — version comparison becomes informational.

2b. Project scaffold version

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.

2c. Marketplace plugin versions

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

2d. Compare

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.

2e. Source-installed AgentPlugin versions

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:

1. Derive owner/repo from the github.com/<owner>/<repo> path segments.
2. Read version metadata from the first available source:
   • package.json version
   • VERSION
   • .claude-plugin/plugin.json version
   • plugin.json version
3. Read git state from inside that directory:
   • current branch or detached HEAD
   • current commit
   • git describe --tags --always when available
   • origin URL when available
   • dirty state from git status --short
   • upstream tracking branch and ahead/behind counts when available
4. Best-effort fetch remote state before ahead/behind comparison. If fetch fails because the user is offline or the remote is unavailable, report remote drift as unknown and keep going.

Do not mutate source AgentPlugin checkouts in /atv-doctor. This phase is read-only except for best-effort git remote metadata fetch.

---

Phase 3: Source AgentPlugin health

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

---

Phase 4: File integrity (project scaffold, manifest required)

Skip this phase entirely when !hasManifest and emit:

⚪ Integrity check requires a manifest. Auto-mode atv init does not write one. Run atv init --guided next 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).

---

Phase 5: Hook validity (project scaffold only)

Skip when !hasProject or .github/hooks/copilot-hooks.json is absent.

1. Parse .github/hooks/copilot-hooks.json as JSON. If parse fails: 🔴 with the parse error and the file path.
2. For each hook entry, walk its referenced script paths under .github/hooks/scripts/. If any referenced script is missing: 🔴 with the missing path and the hook key that references it.
3. If all scripts present: 🟢 with a count of hooks verified.

---

Phase 6: MCP prereqs (project scaffold only)

Skip when !hasProject or .github/copilot-mcp-config.json is absent.

Parse the MCP config:

1. Inputs — read the top-level inputs array (if present). Each entry typically looks like { "id": "github_pat", "type": "promptString", "description": "..." }. List the input IDs that any server depends on.
2. Servers — for each entry under servers, scan its env block for ${input:foo} references. Build a list of which inputs are required by which servers.
3. Document, don't enforce — Copilot CLI prompts for missing inputs at runtime. Just produce a friendly summary:

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.).

---

Phase 7: Optional dep gating

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.

---

Phase 8: Output

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! 🩺"

---

Phase 9: Fix mode (opt-in)

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:

1. Use AskUserQuestion:

   Update <plugin-name> from v to v? (y/n)

2. On confirmation: copilot plugin update <plugin-name>
3. On error: report the failure and continue with the next plugin.

After all fixes, print a summary: "Updated N plugins, skipped M."

Constraints:

• Never auto-rerun atv init (today's installer is additive-only — would not actually refresh files).
• Never modify scaffold files directly.
• Never update, reset, delete, or reinstall VS Code AgentPlugin folders from /atv-doctor.
• Always confirm before running anything.

---

What this skill does NOT do

• Refresh project scaffold files (installer is additive-only today; tracked as future work).
• Update VS Code source-installed AgentPlugins directly (use /atv-update).
• Validate MCP server connectivity (would require network calls to each server).
• Run JSON-schema validation on configs (just parse + key presence).
• Auto-install missing optional dependencies (Bun, agent-browser, gh, az).
• Replace npx atv-starterkit uninstall for full removal.