Docs

# Install Wizard

> Set up the orc plugin interactively — permissions, dependencies, skill packs, CLAUDE.md templates, and a guided tour of all commands.

`/orc:install` is a 7-step setup wizard that configures everything needed to use the orc plugin. It detects your environment (plugin repo vs consumer install, project language), asks before every action via `AskUserQuestion`, and gracefully degrades when optional tools are unavailable. This page covers:

- [Install flow](#install-flow) — what each step does
- [Skill packs](#skill-packs) — bundled dependencies for `/orc:arch` and `/orc:audit`
- [CLAUDE.md templates](#claudemd-templates) — language-specific project templates
- [Optional dependencies](#optional-dependencies) — draw.io, Exa, Ref, agent-browser
- [Troubleshooting](#troubleshooting) — common setup issues and fixes

***

## Install flow

Run `/orc:install` from any project. The wizard adapts based on your environment.

| Step | What it does | User input |
| :--- | :----------- | :--------- |
| **1. Welcome** | Verify `claude --version`, warn if < 1.0.33 | None |
| **2. Plugin status** | Detect plugin repo vs consumer context | None |
| **3. Permissions** | `chmod +x` for scripts, bun setup for hooks | Per-script approve/skip |
| **4. Dependencies** | draw.io, Exa search, Ref docs, agent-browser | Multiselect |
| **4b. Skill packs** | Rust skills for `/orc:arch`, audit skills for `/orc:audit` | Multiselect + location |
| **5. Tutorial** | Quick overview or interactive walkthrough | Choose format |
| **6. CLAUDE.md** | Generate from language-specific template | Generate/skip |
| **7. Done** | Confirmation | None |

### Context detection

The wizard detects two things automatically:

**Plugin vs consumer:**
```bash
ls skills/install/SKILL.md 2>/dev/null && echo "IS_PLUGIN_REPO" || echo "IS_CONSUMER"
```

- **Plugin repo** — running inside the orc repo itself. Notes you can load from any project with `claude --plugin-dir`.
- **Consumer** — plugin installed via `~/.claude/plugins/`. Standard user flow.

**Project type** (for CLAUDE.md generation):

| Marker file | Language | Template |
| :---------- | :------- | :------- |
| `Cargo.toml` | Rust | `CLAUDE-rust.md` |
| `foundry.toml` | Solidity | `CLAUDE-solidity.md` |
| `tsconfig.json` | TypeScript | `CLAUDE-typescript.md` |

If multiple detected, you're asked which is primary.

***

## Skill packs

Step 4b installs bundled skill dependencies needed by two orchestrator skills. These are shipped as zip archives in `skills/install/templates/deps/`.

|                    | Rust pack (`arch-deps.zip`)       | Audit pack (`audit-deps.zip`)           |
| :----------------- | :-------------------------------- | :-------------------------------------- |
| **Size**           | 492K (257 files)                  | 256K (148 files)                        |
| **Required for**   | `/orc:arch`                       | `/orc:audit`                            |
| **Skills**         | 5 skills + 1 agent                | 20 skills                               |
| **Domain**         | Rust development                  | Solidity security auditing              |

### Rust pack contents

| Skill | What it provides |
| :---- | :--------------- |
| `rust-architect` | Architecture patterns, NEVER_DO rules, ownership strategies |
| `rust-skills` | 179 coding rules across 14 categories (naming, ownership, async, errors, perf, testing, API design) |
| `cargo-fuzz` | Fuzz target setup with libFuzzer backend |
| `property-based-testing` | proptest/quickcheck guidance with 7 reference guides |
| `zeroize-audit` | Sensitive data zeroization analysis with 20+ analysis scripts, 7 workflow phases |
| `rust-expert` (agent) | Agent with Rust focus areas and quality checklist |

### Audit pack contents

20 specialized Solidity audit skills organized by the `/orc:audit` wave structure:

- **Recon (3):** entry-point-analyzer, audit-prep-assistant, audit-context-building
- **Domain A (5):** audit-lending, audit-reentrancy, audit-math-precision, audit-oracle, audit-signature
- **Domain B (5):** audit-staking, audit-state-validation, audit-slippage, audit-liquidation, audit-auction
- **Domain C (5):** audit-liquidation-dos, audit-liquidation-calculation, audit-unfair-liquidation, audit-clm, pashov-solidity-auditor
- **Deep (2):** token-integration-analyzer, guidelines-advisor

### Choose where to install

```
1. Global (~/.claude/)  — available to all projects (recommended for personal use)
2. Project (.claude/)   — this project only, can be checked into VCS
```

The wizard checks for existing installations before unzipping. If skills already exist at the target, you're asked whether to overwrite or skip.

***

## CLAUDE.md templates

Step 6 generates a project-specific `CLAUDE.md` from one of three templates:

### Rust template

- Build commands: `cargo build`, `cargo test`, `cargo fmt`, `cargo clippy`
- Style: `#[must_use]`, thiserror/anyhow, no unwrap in libs, `// SAFETY:` for unsafe
- Analysis: `cargo tree`, `cargo-modules` for circular deps, `cargo-deny` audit
- 8 agents: rust-expert, actix-expert, grpc-expert, docker-expert, etc.
- 17+ skill references across Rust, security, and quality categories

### Solidity template

- Build commands: `forge build`, `forge test`, `forge coverage`, `forge fmt`
- Style: NatSpec, custom errors, checks-effects-interactions pattern
- Analysis: Slither, `forge inspect`
- 18+ audit skills organized by vulnerability domain
- Multi-chain vulnerability scanners (Solana, Cairo, Cosmos, Substrate, TON, Algorand)

### TypeScript template

- Build commands: `bun install`, `bun run build`, `bun test`, `bun run lint`
- Style: strict mode, no `any`/`ts-ignore`, interface over type
- Analysis: `madge` for circular deps, `/dive` for call chains
- 23 agents across language, frontend, backend, testing, and build categories
- 9 skills including dive, property-based testing, semgrep, codeql

If a `CLAUDE.md` already exists, you can **merge** (add orc sections, preserve your content), **replace**, or **skip**.

***

## Optional dependencies

Step 4 offers these external tools. All are optional — core orc commands work without them.

| Dependency | What it enables | Setup |
| :--------- | :-------------- | :---- |
| **draw.io** | `/orc:diagram` — generate diagrams from codebase | Clone CLI-Anything + `pip install` + desktop app |
| **Exa search** | Research agents — code context search | Add MCP server to settings.json (API key required) |
| **Ref docs** | Research agents — public documentation search | Add MCP server to settings.json (free) |
| **agent-browser** | `/orc:vibe-code` — browser automation | `npm install -g agent-browser` |
| **Diagram QA** | `/orc:compound-diagram` — diagram quality audit | Python 3.9+ (uses stdlib only) |

### Draw.io setup details

Draw.io requires three components:

1. **CLI-Anything repo** — `git clone https://github.com/HKUDS/CLI-Anything.git ~/git/CLI-Anything`
2. **cli-anything-drawio** — `pip install -e ~/git/CLI-Anything/drawio/agent-harness` (Python 3.10+)
3. **draw.io desktop** — `brew install --cask drawio` (macOS) for PNG/SVG export

The wizard runs a smoke test to verify the full pipeline works: create project, add shape, save, export to PNG, cleanup.

***

## Troubleshooting

### Draw.io issues

| Issue | Cause | Solution |
| :---- | :---- | :------- |
| `command not found: cli-anything-drawio` | pip install failed or wrong PATH | Re-run `pip install -e ~/git/CLI-Anything/drawio/agent-harness` |
| `command not found: drawio` | Desktop app not installed | `brew install --cask drawio` (macOS) |
| `pip install` fails with permissions | System Python restrictions | Use `pip install --user -e ...` |
| `pip install` fails with wrong Python | pip points to Python < 3.10 | Use `pip3 install -e ...` |
| Python version < 3.10 | Homebrew Python outdated | `brew install python@3.12` then retry |
| Export fails | draw.io desktop missing | Install desktop app (CLI-Anything creates files, desktop exports) |
| `git clone` fails | git not installed | `brew install git` or download ZIP |

### Skill pack issues

| Issue | Cause | Solution |
| :---- | :---- | :------- |
| `/orc:arch` says skills not found | Rust pack not installed | Re-run `/orc:install`, select Rust skills in Step 4b |
| `/orc:audit` says skills not found | Audit pack not installed | Re-run `/orc:install`, select Security audit skills |
| Skills installed but not found | Wrong install location | Check if skills are in `~/.claude/skills/` (global) or `.claude/skills/` (project) |
| Overwrite prompt on re-install | Previous installation detected | Choose "Overwrite" to update or "Skip" to keep existing |

### Hook issues

The bundled hook (`.claude/hooks/index.ts`) is a **development stub** that blocks all responses. Do not enable it in settings without editing it first.

***

## Architecture diagram

![Install Wizard Flow](./diagrams/skill-install.png)

***

## Allowed tools

The install skill has a restricted tool set — only what's needed for setup:

| Category | Commands | Purpose |
| :------- | :------- | :------ |
| **Detection** | `claude`, `which`, `test`, `ls`, `find` | Check tool availability and versions |
| **Install** | `npm`, `pip`, `pip3`, `brew`, `git clone` | Install dependencies |
| **Configure** | `chmod`, `mkdir`, `unzip`, `cp` | Set permissions, extract skill packs |
| **Verify** | `cli-anything-drawio`, `drawio`, `python3`, `bun` | Smoke tests and version checks |
| **Cleanup** | `rm` | Remove smoke test artifacts |

**Tip:** The `git clone` command is restricted to `*CLI-Anything*` — the skill cannot clone arbitrary repos.

## See also

- [Arch Skill](./008-arch-skill.md) — uses the Rust skill pack
- [Audit Orchestrator](./009-audit-skill.md) — uses the security audit skill pack
- [Skill Reference](./001-orc-skill-reference.md) — all orc skills overview
- [Setup & Utilities](./006-setup-and-utilities.md) — broader setup context