notque/vexjoy-agent / skills/infrastructure/deploy
deploy
FlaggedDeploy and infrastructure: web deploy, cron, package install, shell configuration.
references/install.md
View on GitHub# /install — Setup & Health Check
Verify your VexJoy Agent installation, diagnose issues, and get oriented. Use after cloning the repo and running `install.sh`, when something seems broken (hooks not firing, missing commands), for first-time orientation, or after a `git pull` to verify nothing broke.
## Instructions
### Phase 1: DIAGNOSE
**Goal**: Run deterministic health checks and report results.
**Step 1: Run install-doctor.py**
```bash
python3 ~/.claude/scripts/install-doctor.py check
```
If the script is not found at `scripts/install-doctor.py`, try `~/.claude/scripts/install-doctor.py`.
**Step 1b: Run runtime health check**
```bash
python3 ~/.claude/scripts/toolkit-health.py --json
```
If the script is not found at `scripts/toolkit-health.py`, try `~/.claude/scripts/toolkit-health.py`. This surfaces runtime health that `install-doctor.py` does not cover: hook crashes (a WARN flag when one hook crashed more than 5 times in 7 days), hook denials (a count, never a flag), stale memory files, state files, and the ADR backlog. It exits 1 when `has_warnings` is true — treat that as "warnings to surface," not a setup failure. Capture the `flags` array for Step 3.
**Step 2: Interpret results**
| Result | Action |
|--------|--------|
| All checks pass | Skip to Phase 3 (Inventory) |
| `~/.claude` missing | Guide user to run `install.sh` — go to Phase 2 |
| Components missing | Guide user to run `install.sh` — go to Phase 2 |
| Codex skill content drift | Run `./install.sh --sync` from the toolkit repo, then re-check |
| Hooks not configured | Guide user to run `install.sh` — go to Phase 2 |
| Broken symlinks | Symlink targets moved. Re-run `install.sh --symlink --force` |
| Python deps missing | Run `pip install -r requirements.txt` from the repo directory |
| Permissions wrong | Run `chmod 755` on affected files |
**Step 3: Display results clearly**
Show the check output to the user with a clear pass/fail summary. Display the raw script output without paraphrasing or reformatting, because the script already formats diagnostics for readability and rewriting them risks losing detail or misrepresenting status.
Append the runtime-health result from Step 1b: if `has_warnings` is true, list each entry from the `flags` array as a WARN line in the summary (for example, stale memory files, or one hook crashing more than 5 times in 7 days). Report the hook denial count as information: a denial is a hook doing its job, and it never raises a flag. When `has_warnings` is false, report runtime health as OK. WARN flags are advisory — they inform the user without blocking the pass/fail verdict for setup.
**Gate**: Health check complete. If issues found, proceed to Phase 2. If clean, skip to Phase 3.
### Phase 2: FIX (only if issues found)
**Goal**: Guide the user through fixing detected issues.
**Step 1: Determine if install.sh needs to run**
If `~/.claude` is missing or components are not installed, the user needs to run install.sh. Tell them:
```
The toolkit hasn't been installed yet. Run this from the repo directory:
./install.sh --symlink # recommended: updates with git pull
./install.sh --dry-run # preview first
```
Wait for the user to confirm they've run it, then re-run the health check. This phase is interactive because installation changes system state -- always show the user what needs fixing and let them choose before acting.
**Step 2: Fix individual issues**
For fixable issues (permissions, missing deps), offer to fix them:
```bash
# Fix permissions
find ~/.claude/hooks -name "*.py" -exec chmod 755 {} \;
find ~/.claude/scripts -name "*.py" -exec chmod 755 {} \;
# Install Python deps (from repo directory)
pip install -r requirements.txt
```
Only run fixes the user approves, because automated fixes to `~/.claude` can break an existing setup if assumptions about the environment are wrong.
**Step 3: Re-check**
After fixes, re-run:
```bash
python3 ~/.claude/scripts/install-doctor.py check
```
`--sync` refreshes canonical Codex skill content, including changed files and
new references inside an existing skill. It preserves Codex-only skill entries.
**Gate**: All checks pass. Proceed to Phase 3.
### Phase 3: INVENTORY
**Goal**: Show the user what they have installed.
**Step 1: Run inventory**
```bash
python3 ~/.claude/scripts/install-doctor.py inventory
```
**Step 2: Display summary**
Show the actual counts returned by `install-doctor.py inventory` -- never display hardcoded numbers, because component counts change with every install and stale numbers erode trust. Present them as:
```
Your toolkit is ready. Here's what's installed:
Agents: [N] specialized domain experts
Skills: [N] workflow methodologies ([N] user-invocable)
Hooks: [N] automation hooks
Commands: [N] slash commands
Scripts: [N] utility scripts
```
**Gate**: User sees their inventory. Proceed to Phase 3.5.
### Phase 3.5: MCP INVENTORY
**Goal**: Show which MCP servers are available and their status.
**Step 1: Run MCP registry check**
```bash
python3 ~/.claude/scripts/mcp-registry.py list
```
If the script is not found at `scripts/mcp-registry.py`, try `~/.claude/scripts/mcp-registry.py`.
**Step 2: Display MCP status**
Show the MCP inventory as:
```
MCP Servers:
[✓] Chrome DevTools MCP — Live browser debugging
Paired skills: wordpress-live-validation
[✓] Playwright MCP — Automated browser testing
Paired skills: wordpress-live-validation
[✓] gopls MCP — Go workspace intelligence
Paired skills: go-patterns
[✗] Context7 MCP — Library documentation lookups
Install: claude mcp add context7 -- npx @anthropic-ai/mcp-context7@latest
```
Use checkmark for connected MCPs and X for missing ones. For missing MCPs, show the install command.
**Gate**: MCP inventory displayed. Proceed to Phase 4.
### Phase 4: ORIENT
**Goal**: Give the user their bearings -- what to do first.
**Step 1: Show the three essential commands**
```
Getting started:
/do [describe what you want] — routes to the right agent + skill
/comprehensive-review — 20+ reviewer agents in 3 waves
/install — run this again anytime to check health
```
**Step 2: Show a few practical examples**
```
Try these:
/do debug this failing test
/do review my Go code for quality
/do write a blog post about [topic]
/do create a voice profile from my writing samples
```
**Step 3: Mention the docs**
```
Documentation:
docs/QUICKSTART.md — 30-second overview
docs/REFERENCE.md — quick reference card
```
**Gate**: User is oriented. Installation complete.
## Error Handling
### Error: install-doctor.py not found
The script hasn't been installed yet. Check if the user is in the repo directory. If so, run it directly from `scripts/`. If not, guide them to clone and install first.
### Error: Permission denied on install.sh
Run `chmod +x install.sh` first.
### Error: Python not found
The toolkit requires Python 3.10+. Guide the user to install Python for their platform.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |