# Install

> Set up the orc plugin (permissions, draw.io diagrams, MCP tools) and get a guided tour of available commands.

- **Type:** Skill
- **Install:** `agentstack add skill-qgolem-orc-install`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qGolem](https://github.com/qGolem)
- **Source:** https://github.com/qGolem/orc/tree/main/skills/install

## Install

```sh
agentstack add skill-qgolem-orc-install
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 /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 `. 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

  /     │\n│    └─ .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//     │\n│    └─ .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"}
    ]'
  />

```

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

  

```

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

  ?"
    header=""
    multiSelect="false"
    options='[
      {"label": "Grant", "description": "chmod +x "},
      {"label": "Skip", "description": "Don't grant permission"}
    ]'
  />

```

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

### Step 4: Optional dependencies

```xml

  

```

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 /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

  

```

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

  

```

If any packs selected, ask where to install:

```xml

  

```

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

  

```

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

  

```

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//` and re-run unzip |

### Step 5: Tutorial

```xml

  

```

**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

  

```

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//PROJECT.md
  .claude/plans//ROADMAP.md
  .claude/plans//phases/01-name/PLAN.md
```

```xml

  

```

**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

  

```

**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

  

```

**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

  

```

**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

  

```

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

  

```

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/instal

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [qGolem](https://github.com/qGolem)
- **Source:** [qGolem/orc](https://github.com/qGolem/orc)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qgolem-orc-install
- Seller: https://agentstack.voostack.com/s/qgolem
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.