Install

Install

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

Process

Step 1: Welcome and Verify Claude Code

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 "ISPLUGINREPO" || 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:

  /     │\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:

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:

  ?"
    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

For each selected dependency, provide the exact setup instructions:

draw.io diagrams:

Check what's already installed:

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

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

If not found:

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

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

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

# 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:

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 |

If any packs selected, ask where to install:

Set $TARGET based on selection:

• Global: ~/.claude
• Project: .claude

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

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

# 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:

If installing:

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

Verify Rust pack — check every expected file:

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

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

Same overwrite prompt pattern. If installing:

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

Verify Audit pack — check every expected file:

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:

If "All good": continue to Step 5.

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

# 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

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:

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

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

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"

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

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

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

If "Generate":

1. Detect project type:

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

1. Resolve template directory:

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