Install

---
description: Set up the orc plugin (permissions, draw.io diagrams, MCP tools) and get a guided tour of available commands.
argument-hint:
allowed-tools:
  - Read
  - Bash(claude:*)
  - Bash(which:*)
  - Bash(npx:*)
  - Bash(npm:*)
  - Bash(chmod:*)
  - Bash(cat:*)
  - Bash(ls:*)
  - Bash(echo:*)
  - Bash(find:*)
  - Bash(bun:*)
  - Bash(brew:*)
  - Bash(pip:*)
  - Bash(pip3:*)
  - Bash(git clone *CLI-Anything*)
  - Bash(python3:*)
  - Bash(cli-anything-drawio:*)
  - Bash(drawio:*)
  - Bash(mkdir:*)
  - Bash(rm:*)
  - Bash(test:*)
  - Bash(unzip:*)
  - Bash(cp:*)
  - Glob
  - Grep
  - AskUserQuestion
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

# Install

Interactive setup wizard for the orc plugin. Uses AskUserQuestion for every decision point.

## Process

### Step 1: Welcome and Verify Claude Code

```bash
claude --version 2>/dev/null || echo "NOT_FOUND"
```

If NOT_FOUND: tell user to install Claude Code first, then re-run `/orc:install`.

Otherwise extract version. If < 1.0.33, warn that some features may not work.

Display welcome:

```
Welcome to orc — orchestrated planning and code review for Claude Code.
```

### Step 2: Check plugin status

The fact that this skill is running means the plugin is loaded. Confirm this.

Determine context:

```bash
ls skills/install/SKILL.md 2>/dev/null && echo "IS_PLUGIN_REPO" || echo "IS_CONSUMER"
```

**If IS_PLUGIN_REPO:** Note they can load from any project with `claude --plugin-dir /path/to/this/repo`.

**If IS_CONSUMER:** Plugin is installed correctly.

### Step 3: Script permissions and runtime setup

Discover all scripts and hooks that need execution access:

```bash
find skills/ .claude/skills/ -name "*.sh" -type f 2>/dev/null
ls .claude/hooks/index.ts 2>/dev/null && echo "HAS_HOOKS" || true
```

For **each** script found, present an AskUserQuestion with:
1. A description of what the script does
2. An ASCII diagram of its execution flow
3. A choice to grant execute permission or skip

**Important:** Check current permissions first with `ls -la <path>`. If already executable, note this and skip the question.

---

#### Script: `skills/half-clone/scripts/half-clone-conversation.sh`

**What it does:** Clones the later half of a Claude Code conversation into a new session, discarding earlier context to free tokens. Used by `/orc:half-clone`.

Present this to the user:

```xml
<AskUserQuestion>
  <Question
    question="Grant execute permission to half-clone-conversation.sh?"
    header="half-clone"
    multiSelect="false"
    options='[
      {"label": "Grant (Recommended)",
       "description": "chmod +x — required for /orc:half-clone to work",
       "preview": "half-clone-conversation.sh (575 lines)\n\nUsed by: /orc:half-clone\nRuntime: bash 3.2+ (macOS/Linux)\nInput:   session-id, project-path\nOutput:  new .jsonl conversation file\n\n┌─────────────────────────────────────┐\n│  /orc:half-clone                    │\n│  └─ calls half-clone-conversation.sh│\n└──────────────┬──────────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│ 1. Find conversation .jsonl      │\n│    ~/.claude/projects/<dir>/     │\n│    └─ <session-id>.jsonl         │\n└──────────────┬───────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│ 2. Count clean user messages     │\n│    Filter: type=user, skip meta  │\n│    Calculate halfway point       │\n└──────────────┬───────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│ 3. Generate new session UUID     │\n│    Pre-generate UUIDs for awk    │\n│    (batch, not per-line)         │\n└──────────────┬───────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│ 4. Single-pass awk transform     │\n│    ├─ Skip first N lines         │\n│    ├─ Remap session/msg UUIDs    │\n│    ├─ Strip thinking blocks      │\n│    ├─ Halve token counts         │\n│    └─ Tag first kept message     │\n└──────────────┬───────────────────┘\n               │\n               ▼\n┌──────────────────────────────────┐\n│ 5. Write new .jsonl + history    │\n│    ~/.claude/projects/<dir>/     │\n│    └─ <new-session>.jsonl        │\n│    ~/.claude/history.jsonl       │\n│    └─ append entry               │\n└──────────────────────────────────┘\n\nSafe: reads original, writes new file.\nNo destructive operations."},
      {"label": "Skip",
       "description": "Don't grant — /orc:half-clone won't work until you do"}
    ]'
  />
</AskUserQuestion>
```

If "Grant": run `chmod +x skills/half-clone/scripts/half-clone-conversation.sh` (and the `.claude/skills/` copy if it exists).

---

#### Hook: `.claude/hooks/index.ts`

**What it does:** A Claude Code stop hook written in TypeScript that runs via `bun`. Currently a development stub — it blocks all responses and logs git status.

Present this to the user:

```xml
<AskUserQuestion>
  <Question
    question="The hooks file (.claude/hooks/index.ts) requires bun to execute. Set up bun?"
    header="Hooks"
    multiSelect="false"
    options='[
      {"label": "Install bun (Recommended)",
       "description": "Required for hooks to work. Runs: npm install -g bun",
       "preview": ".claude/hooks/index.ts (15 lines)\n\nType:    StopHook (runs after each response)\nRuntime: bun (TypeScript)\nSDK:     @anthropic-ai/claude-agent-sdk\n\n┌─────────────────────────────────────┐\n│  Claude generates a response        │\n└──────────────┬──────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────┐\n│  Hook: .claude/hooks/index.ts       │\n│  Executed by: bun                   │\n│                                     │\n│  stdin ──▶ StopHookInput (JSON)     │\n│                                     │\n│  1. Parse input from stdin          │\n│  2. stdout: {decision, reason}      │\n│     decision: \"block\" | \"approve\"   │\n│  3. Check git status                │\n│  4. Log if files changed            │\n└──────────────┬──────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────┐\n│  Claude Code reads stdout           │\n│  \"block\"  → re-generates response   │\n│  \"approve\" → sends to user          │\n└─────────────────────────────────────┘\n\nNote: Currently hardcoded to \"block\".\nThis is a dev stub — you may want to\nedit it before enabling hooks."},
      {"label": "Already have bun",
       "description": "Skip install — just verify bun is available"},
      {"label": "Skip",
       "description": "Don't set up bun — hooks won't work"}
    ]'
  />
</AskUserQuestion>
```

If "Install bun": run `npm install -g bun` and verify with `which bun`.
If "Already have bun": run `which bun` to verify.
If either verified, warn:

```
Note: .claude/hooks/index.ts currently blocks ALL responses
(hardcoded decision: "block"). Edit it before enabling hooks
in your settings, or it will prevent Claude from responding.
```

---

#### Future scripts

If `find` discovers any `.sh` files beyond the known ones above, present each with:

```xml
<AskUserQuestion>
  <Question
    question="Grant execute permission to <filename>?"
    header="<short-name>"
    multiSelect="false"
    options='[
      {"label": "Grant", "description": "chmod +x <path>"},
      {"label": "Skip", "description": "Don't grant permission"}
    ]'
  />
</AskUserQuestion>
```

Read the script first to provide an accurate description and diagram in the preview.

### Step 4: Optional dependencies

```xml
<AskUserQuestion>
  <Question
    question="Want to set up optional external tools? These enhance research and design commands but aren't required."
    header="Dependencies"
    multiSelect="true"
    options='[
      {"label": "draw.io diagrams", "description": "cli-anything-drawio + draw.io desktop for /orc:diagram. Requires Python 3.10+."},
      {"label": "Exa search", "description": "Code context search for research agents. Requires API key from exa.ai."},
      {"label": "Ref docs", "description": "Public documentation search for research agents. Free, no API key."},
      {"label": "agent-browser", "description": "Browser automation for /orc:vibe-code and frontend verification."},
      {"label": "Diagram quality audit", "description": "Python scripts for /orc:compound-diagram. Verifies Python 3.9+ is available."},
      {"label": "Skip all", "description": "Set up nothing — I can add these later."}
    ]'
  />
</AskUserQuestion>
```

For each selected dependency, provide the exact setup instructions:

**draw.io diagrams:**

Check what's already installed:

```bash
which cli-anything-drawio 2>/dev/null && echo "cli-anything-drawio: INSTALLED" || echo "cli-anything-drawio: NOT FOUND"
which drawio 2>/dev/null && echo "drawio desktop: INSTALLED" || echo "drawio desktop: NOT FOUND"
python3 --version 2>/dev/null && echo "Python3: OK" || echo "Python3: NOT FOUND (required)"
```

Skip any sub-step where the tool is already installed.

**4a. Clone CLI-Anything repo** (if `cli-anything-drawio` not found):

```bash
# Check if already cloned
find ~/git ~/projects ~/repos ~/code ~ -maxdepth 3 -name "CLI-Anything" -type d 2>/dev/null | head -1
```

If not found:

```bash
mkdir -p ~/git
git clone https://github.com/HKUDS/CLI-Anything.git ~/git/CLI-Anything
```

**4b. Install cli-anything-drawio** (if not found):

```bash
pip install -e ~/git/CLI-Anything/drawio/agent-harness
```

Requires Python 3.10+ with `click>=8.0.0` and `prompt-toolkit>=3.0.0`.
If `pip` fails, try `pip3 install -e ~/git/CLI-Anything/drawio/agent-harness`.

**4c. Install draw.io desktop** (if not found):

```bash
# macOS
brew install --cask drawio
```

Other platforms:
- **Linux:** `snap install drawio` or download from https://github.com/jgraph/drawio-desktop/releases
- **Windows:** `winget install JGraph.Draw`

Without this, `.drawio` files can still be created — but no PNG/SVG/PDF export from CLI.

**4d. Verify draw.io setup:**

```bash
cli-anything-drawio --help && echo "--- cli-anything-drawio OK ---"
drawio --version 2>/dev/null && echo "--- drawio desktop OK ---"

# Smoke test: create, export, cleanup
cli-anything-drawio --json project new --preset letter -o /tmp/test-drawio.drawio
cli-anything-drawio --json --project /tmp/test-drawio.drawio shape add rounded --label "Test" --x 100 --y 100
cli-anything-drawio --json --project /tmp/test-drawio.drawio project save /tmp/test-drawio.drawio
drawio --export --format png --output /tmp/test-drawio.png /tmp/test-drawio.drawio 2>/dev/null && echo "--- export OK ---"
rm -f /tmp/test-drawio.drawio /tmp/test-drawio.png
```

If any step fails, show the relevant troubleshooting:

| Problem | Fix |
|---------|-----|
| `command not found: cli-anything-drawio` | Re-run `pip install -e ~/git/CLI-Anything/drawio/agent-harness` |
| `command not found: drawio` | `brew install --cask drawio` (macOS) |
| `pip install` fails with permissions | Use `pip install --user -e ...` |
| `pip install` fails with wrong Python | Use `pip3 install -e ...` |
| Python version < 3.10 | `brew install python@3.12` then retry with `pip3` |
| Export says "draw.io CLI not found" | Install draw.io desktop app (step 4c) |
| `git clone` fails | `brew install git` first, or download ZIP from GitHub |
| Repo already exists at target | `pip install -e` still works — just re-run step 4b |

After setup, use `/orc:diagram` to generate diagrams from your codebase.

**Exa:**
```
Add to ~/.claude/settings.json under "mcpServers":

"exa": {
  "command": "npx",
  "args": ["-y", "exa-mcp-server"],
  "env": { "EXA_API_KEY": "your-key-here" }
}

Get your API key at https://exa.ai
```

**Ref:**
```
Add to ~/.claude/settings.json under "mcpServers":

"Ref": {
  "command": "npx",
  "args": ["-y", "ref-mcp-server"]
}
```

**agent-browser:**
```bash
npm install -g agent-browser
```
Then verify: `which agent-browser`

**Diagram quality audit:**

Check Python is available:
```bash
python3 --version 2>/dev/null
```
If Python 3.9+, report ready. No additional packages needed (uses stdlib `xml.etree` only).
If not found, tell user: "Python 3.9+ required for /orc:compound-diagram audit scripts."

After showing instructions for selected deps, confirm:

```xml
<AskUserQuestion>
  <Question
    question="Were you able to set up the dependencies? (You can always do this later)"
    header="Status"
    multiSelect="false"
    options='[
      {"label": "All set", "description": "Dependencies configured successfully"},
      {"label": "Need help", "description": "Something didn't work — show me more details"},
      {"label": "I'll do it later", "description": "Continue with the tutorial"}
    ]'
  />
</AskUserQuestion>
```

If "Need help": read their `~/.claude/settings.json` and help troubleshoot.

### Step 4b: Skill dependencies for /orc:arch and /orc:audit

Two orchestrator skills require specialized skill packs to function. These are bundled as zip archives.

| Pack | Skills | Size | Required for |
|------|--------|------|-------------|
| **Rust** | rust-architect, rust-skills (179 rules), cargo-fuzz, property-based-testing, zeroize-audit + rust-expert agent | 492K | `/orc:arch` |
| **Security audit** | 20 Solidity audit skills (lending, reentrancy, oracle, slippage, etc.) | 256K | `/orc:audit` |

```xml
<AskUserQuestion>
  <Question
    question="Install skill dependencies for orchestrator skills?"
    header="Skill Packs"
    multiSelect="true"
    options='[
      {"label": "Rust skills for /orc:arch",
       "description": "5 skills + 1 agent: rust-architect, rust-skills (179 rules), cargo-fuzz, property-based-testing, zeroize-audit, rust-expert agent",
       "preview": "Required by /orc:arch to design Rust projects.\n\nrust-architect  — Architecture patterns, NEVER_DO rules, ownership strategies\nrust-skills     — 179 Rust coding rules across 14 categories\ncargo-fuzz      — Fuzz target setup with libFuzzer backend\nproperty-based  — proptest/quickcheck guidance\nzeroize-audit   — Sensitive data zeroization analysis\nrust-expert     — Agent with Rust focus areas + quality checklist"},
      {"label": "Security audit skills for /orc:audit",
       "description": "20 specialized Solidity audit skills covering lending, reentrancy, oracles, liquidation, staking, signatures, and more",
       "preview": "Required by /orc:audit for parallel security auditing.\n\nWave 1 — Recon:\n  entry-point-analyzer, audit-prep-assistant, audit-context-building\n\nWave 2-4 — Domain Scans:\n  audit-lending, audit-reentrancy, audit-math-precision,\n  audit-oracle, audit-signature, audit-staking,\n  audit-state-validation, audit-slippage, audit-liquidation,\n  audit-auction, audit-liquidation-dos,\n  audit-liquidation-calculation, audit-unfair-liquidation,\n  audit-clm, pashov-solidity-auditor\n\nWave 5 — Deep Analysis:\n  token-integration-analyzer, guidelines-advisor"},
      {"label": "Skip",
       "description": "Don't install — /orc:arch and /orc:audit won't work without these"}
    ]'
  />
</AskUserQuestion>
```

If any packs selected, ask where to install:

```xml
<AskUserQuestion>
  <Question
    question="Where should the skills be installed?"
    header="Install Location"
    multiSelect="false"
    options='[
      {"label": "Project (.claude/) (Recommended)",
       "description": "This project only. Skills live next to the code that uses them. Check into VCS to share with team."},
      {"label": "Global (~/.claude/)",
       "description": "Available to all projects. You will need to adjust skill paths in /orc:arch if using this option."}
    ]'
  />
</AskUserQuestion>
```

Set `$TARGET` based on selection:
- Global: `~/.claude`
- Project: `.claude`

Resolve the zip directory (same pattern as CLAUDE.md templates):

```bash
if [ -d skills/install/templates/deps ]; then
  echo "DEPS_DIR=skills/install/templates/deps"
else
  find ~/.claude/plugins -path "*/install/templates/deps" -type d 2>/dev/null | head -1
fi
```

For each selected pack:

**Rust pack (`arch-deps.zip`):**

```bash
# Check if already installed
ls $TARGET/skills/rust-architect/SKILL.md 2>/dev/null && echo "RUST_EXISTS" || echo "RUST_NOT_FOUND"
```

If RUST_EXISTS, ask:

```xml
<AskUserQuestion>
  <Question
    question="Rust skills already installed at $TARGET. Overwrite?"
    header="Existing Installation"
    multiSelect="false"
    options='[
      {"label": "Overwrite", "description": "Replace with bundled version"},
      {"label": "Skip", "description": "Keep existing installation"}
    ]'
  />
</AskUserQuestion>
```

If installing:

```bash
mkdir -p $TARGET/skills $TARGET/agents
unzip -o $DEPS_DIR/arch-deps.zip -d $TARGET
```

**Verify Rust pack — check every expected file:**

```bash
RUST_OK=0
RUST_FAIL=0
for skill in rust-architect rust-skills cargo-fuzz property-based-testing zeroize-audit; do
  test -f $TARGET/skills/$skill/SKILL.md && RUST_OK=$((RUST_OK+1)) || RUST_FAIL=$((RUST_FAIL+1))
done
test -f $TARGET/agents/rust-expert.md && RUST_OK=$((RUST_OK+1)) || RUST_FAIL=$((RUST_FAIL+1))
ls $TARGET/skills/rust-skills/rules/*.md 2>/dev/null | wc -l
echo "RUST_OK=$RUST_OK RUST_FAIL=$RUST_FAIL"
```

Expected: `RUST_OK=6 RUST_FAIL=0`, 179 rule files.

If any failures, report which files are missing and suggest:
- Re-run unzip: `unzip -o $DEPS_DIR/arch-deps.zip -d $TARGET`
- Check disk space: `df -h $TARGET`
- Check permissions: `ls -la $TARGET/skills/`

**Audit pack (`audit-deps.zip`):**

```bash
ls $TARGET/skills/entry-point-analyzer/SKILL.md 2>/dev/null && echo "AUDIT_EXISTS" || echo "AUDIT_NOT_FOUND"
```

Same overwrite prompt pattern. If installing:

```bash
mkdir -p $TARGET/skills
unzip -o $DEPS_DIR/audit-deps.zip -d $TARGET
```

**Verify Audit pack — check every expected file:**

```bash
AUDIT_OK=0
AUDIT_FAIL=0
for skill in entry-point-analyzer audit-prep-assistant audit-context-building audit-lending audit-reentrancy audit-math-precision audit-oracle audit-signature audit-staking audit-state-validation audit-slippage audit-liquidation audit-auction audit-liquidation-dos audit-liquidation-calculation audit-unfair-liquidation audit-clm pashov-solidity-auditor token-integration-analyzer guidelines-advisor; do
  test -f $TARGET/skills/$skill/SKILL.md && AUDIT_OK=$((AUDIT_OK+1)) || AUDIT_FAIL=$((AUDIT_FAIL+1))
done
echo "AUDIT_OK=$AUDIT_OK AUDIT_FAIL=$AUDIT_FAIL"
```

Expected: `AUDIT_OK=20 AUDIT_FAIL=0`.

If any failures, report which skills are missing and suggest same fixes as Rust pack.

**Present verification results via AskUserQuestion:**

```xml
<AskUserQuestion>
  <Question
    question="Skill pack installation complete. Verify the results below."
    header="Verification"
    multiSelect="false"
    options='[
      {"label": "All good",
       "description": "Continue to the next step",
       "preview": "[Insert verification summary here]\n\nRust pack: X/6 files OK, 179 rule files\nAudit pack: Y/20 skills OK\n\nInstalled to: $TARGET\n\nIf all counts match, /orc:arch and /orc:audit are ready to use."},
      {"label": "Something is wrong",
       "description": "Show troubleshooting steps"}
    ]'
  />
</AskUserQuestion>
```

If "All good": continue to Step 5.

If "Something is wrong": display the failed file list and run diagnostics:

```bash
# Check disk space
df -h $TARGET

# Check permissions
ls -la $TARGET/skills/ | head -10

# Check zip integrity
unzip -t $DEPS_DIR/arch-deps.zip 2>&1 | tail -1
unzip -t $DEPS_DIR/audit-deps.zip 2>&1 | tail -1
```

Present findings and suggest:

| Issue | Fix |
|-------|-----|
| No space left | Free disk space, retry |
| Zip corrupt | Re-download the orc plugin, retry `/orc:install` |
| Partial install | Delete `$TARGET/skills/<broken>/` and re-run unzip |

### Step 5: Tutorial

```xml
<AskUserQuestion>
  <Question
    question="Want a guided tour of what orc can do?"
    header="Tutorial"
    multiSelect="false"
    options='[
      {"label": "Quick overview", "description": "One-page summary of all commands and when to use them (Recommended)"},
      {"label": "Interactive walkthrough", "description": "Step-by-step tour of each command group with examples"},
      {"label": "Skip", "description": "I'll explore on my own"}
    ]'
  />
</AskUserQuestion>
```

**If Quick overview:**

Display the full command reference:

```
## orc commands

### Planning (start here)
  /orc:spec "prompt"     — Full orchestrated planning pipeline
                            discover → research → clarify → generate
                            Produces: PROJECT.md, ROADMAP.md, phase PLANs

### Codebase Analysis
  /orc:map               — 11-agent parallel codebase scan
                            Produces: .claude/context/ (14 documents)
  /orc:adr "slug N"      — Research + write architectural decision record

### Implementation
  /orc:swarm "task"      — Plan a multi-agent team from a phase PLAN
  /orc:phase-research    — Deep research before implementing a phase
### Code Quality
  /orc:review            — 5-agent parallel code review
  /orc:stress-test       — Adversarial plan testing against real docs

### Documentation
  /orc:compound-pr       — Pre-PR documentation pipeline
  /orc:compound-md       — Review conversations for CLAUDE.md improvements
  /orc:compound-memory   — Extract session patterns to project memory

### Design
  /orc:vibe-code         — UI design + browser verification
  /orc:design-system     — Brand reference (colors, typography, layout)

### Diagrams
  /orc:diagram "focus"   — Generate draw.io diagrams from codebase
                            Requires cli-anything-drawio (set up in /orc:install)

### Utilities
  /orc:install           — This setup wizard
  /orc:half-clone        — Clone conversation half to save tokens

## Typical workflow

  1. /orc:map                — understand the codebase
  2. /orc:spec "feature"     — plan the feature
  3. /orc:swarm              — implement each phase
  4. /orc:review             — review the changes
  5. /orc:compound-pr        — generate PR documentation
```

Then:

```xml
<AskUserQuestion>
  <Question
    question="Want to dive deeper into any command group?"
    header="Deep dive"
    multiSelect="false"
    options='[
      {"label": "Planning", "description": "/orc:spec — the main entry point and planning pipeline"},
      {"label": "Implementation", "description": "/orc:swarm, /orc:phase-research — execution agents"},
      {"label": "All good", "description": "I have what I need"}
    ]'
  />
</AskUserQuestion>
```

If they pick a group, explain it in detail (what it does, what files it produces, when to use it, example invocation), then ask if they want another group.

**If Interactive walkthrough:**

Walk through each command group one at a time. For each group:

1. Explain what it does and when to use it
2. Show the command syntax
3. Describe what it produces (output files/artifacts)
4. Give a concrete example

Groups in order:

**Group 1: Planning**

```
/orc:spec is the main entry point. It runs 4 sub-phases:

  1. discover  — scans codebase, writes STATE.md
  2. research  — 4 parallel web researchers, writes research/SUMMARY.md
  3. clarify   — interactive Q&A to sharpen requirements
  4. generate  — creates ROADMAP.md + per-phase PLANs

Example:
  /orc:spec "add user authentication with OAuth"

Produces:
  .claude/plans/<slug>/PROJECT.md
  .claude/plans/<slug>/ROADMAP.md
  .claude/plans/<slug>/phases/01-name/PLAN.md
```

```xml
<AskUserQuestion>
  <Question
    question="Ready for the next group?"
    header="Continue"
    multiSelect="false"
    options='[
      {"label": "Next: Codebase Analysis", "description": "/orc:map and /orc:adr"},
      {"label": "Done", "description": "End the tour here"}
    ]'
  />
</AskUserQuestion>
```

**Group 2: Codebase Analysis**

```
/orc:map spawns 11 parallel agents to analyze your codebase.
Each agent writes a document to .claude/context/:

  STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md,
  CONVENTIONS.md, TESTING.md, CONCERNS.md, REPO.md,
  PATTERNS.md, HISTORY.md, TYPES.md, TEST-QUALITY.md,
  CODEMAP.md, UX-PATTERNS.md

Use BEFORE /orc:spec on brownfield projects.

/orc:adr researches and writes Architectural Decision Records.

Example:
  /orc:adr "my-feature 1"  — research ADR for phase 1
```

```xml
<AskUserQuestion>
  <Question
    question="Ready for the next group?"
    header="Continue"
    multiSelect="false"
    options='[
      {"label": "Next: Implementation", "description": "/orc:swarm, /orc:phase-research"},
      {"label": "Done", "description": "End the tour here"}
    ]'
  />
</AskUserQuestion>
```

**Group 3: Implementation**

```
/orc:swarm plans a multi-agent team to implement a phase.
It reads the PLAN.md, explores the codebase, and outputs a
TEAM-PLAN.md with agent prompts you can spawn.

/orc:phase-research does deep research before implementation.
Spawns a researcher agent that reads your plan + web docs.

Example:
  /orc:swarm "implement phase 1: authentication"
```

```xml
<AskUserQuestion>
  <Question
    question="Ready for the next group?"
    header="Continue"
    multiSelect="false"
    options='[
      {"label": "Next: Code Quality", "description": "/orc:review, /orc:stress-test"},
      {"label": "Done", "description": "End the tour here"}
    ]'
  />
</AskUserQuestion>
```

**Group 4: Code Quality**

```
/orc:review launches 5 specialized review agents in parallel:
  - Code reviewer (CLAUDE.md compliance, security, quality)
  - Silent failure hunter (empty catches, swallowed errors)
  - Security reviewer (OWASP, secrets, injection)
  - Type design analyzer (invariant strength)
  - Test analyzer (coverage gaps)

/orc:stress-test adversarially tests a plan against real docs
and runs proof-of-concept code before you build.

Example:
  /orc:review        — review current changes
  /orc:stress-test   — verify a plan is sound
```

```xml
<AskUserQuestion>
  <Question
    question="Ready for the next group?"
    header="Continue"
    multiSelect="false"
    options='[
      {"label": "Next: Documentation", "description": "/orc:compound-pr, compound-md, compound-memory"},
      {"label": "Done", "description": "End the tour here"}
    ]'
  />
</AskUserQuestion>
```

**Group 5: Documentation**

```
/orc:compound-pr — Pre-PR pipeline. Research agents build
context, synthesis agents produce a docs page as PR description.

/orc:compound-md — Reviews recent conversations and suggests
improvements to your CLAUDE.md files.

/orc:compound-memory — Extracts patterns from the current
session and saves them as decision trees to project memory.

Example:
  /orc:compound-pr     — before creating a PR
  /orc:compound-md     — periodic CLAUDE.md maintenance
```

```xml
<AskUserQuestion>
  <Question
    question="That covers all the main commands. Anything else?"
    header="Wrap up"
    multiSelect="false"
    options='[
      {"label": "All good", "description": "I'm ready to start using orc"},
      {"label": "Tell me about Design", "description": "/orc:vibe-code and /orc:design-system"}
    ]'
  />
</AskUserQuestion>
```

If they ask about Design, explain the Octant V2 specific skills.

**If Skip:**

```
You're all set. Start with:
  /orc:map     — to analyze an existing codebase
  /orc:spec    — to plan a new feature

Run /orc:install again anytime for this tour.
```

### Step 6: Generate project CLAUDE.md

```xml
<AskUserQuestion>
  <Question
    question="Generate a project-specific CLAUDE.md for your codebase?"
    header="CLAUDE.md Generation"
    multiSelect="false"
    options='[
      {"label": "Generate (Recommended)",
       "description": "Detect project type and copy the matching template (Rust, Solidity, or TypeScript)"},
      {"label": "Skip",
       "description": "Don't generate — I'll write my own CLAUDE.md"}
    ]'
  />
</AskUserQuestion>
```

If "Generate":

1. **Detect project type:**

```bash
test -f Cargo.toml && echo "RUST" || true
test -f foundry.toml && echo "SOLIDITY" || true
test -f tsconfig.json && echo "TYPESCRIPT" || true
```

2. **Resolve template directory:**

```bash
# Plugin repo context
if [ -d skills/install/templates ]; then
  echo "TEMPLATE_DIR=skills/install/templates"
else
  # Consumer context — find via plugin install path
  find ~/.claude/plugins -path "*/install/templates" -type d 2>/dev/null | head -1
fi
```

3. **Copy the matching template:**

| Detected | Template file |
|----------|--------------|
| `foundry.toml` | `CLAUDE-solidity.md` |
| `Cargo.toml` | `CLAUDE-rust.md` |
| `tsconfig.json` | `CLAUDE-typescript.md` |

If multiple detected, ask the user which one is primary. Read the template file and write it to `CLAUDE.md` in the project root.

4. **Check for existing CLAUDE.md first:**

```bash
test -f CLAUDE.md && echo "CLAUDE_MD_EXISTS" || echo "CLAUDE_MD_NOT_FOUND"
```

If CLAUDE_MD_EXISTS:

```xml
<AskUserQuestion>
  <Question
    question="A CLAUDE.md already exists. What would you like to do?"
    header="Existing CLAUDE.md"
    multiSelect="false"
    options='[
      {"label": "Merge", "description": "Add orc sections to existing CLAUDE.md (preserves your content)"},
      {"label": "Replace", "description": "Replace with the template version"},
      {"label": "Skip", "description": "Keep the existing file unchanged"}
    ]'
  />
</AskUserQuestion>
```

### Step 7: Done

```
Setup complete. Run any /orc:* command to get started.
```