# Installing Roo/Zoo Code on Your Home Machine

Step-by-step guide to set up the sanitized home configuration.

---

## Prerequisites

- **VS Code** installed (or compatible editor)
- **Roo Code** or **Zoo Code** extension installed from marketplace
- An API key from one of:
  - [Anthropic](https://console.anthropic.com/) — best quality (Claude Opus 4, Sonnet 4)
  - [OpenRouter](https://openrouter.ai/) — best variety + cost savings (access to DeepSeek, Gemini, Llama, etc.)
  - [Ollama](https://ollama.com/) — fully local, free (requires decent GPU)

---

## Step 1: Copy Mode Configuration

```bash
cp home/.roomodes ~/.roo/.roomodes
```

This gives you 5 custom modes:
- 🪃 Orchestrator (Lumen identity)
- 🧩 Skill Writer
- ✍️ Mode Writer
- 🛠️ Tool Writer
- 🎨 Visual QA

Plus the built-in modes: architect, code, ask, debug.

---

## Step 2: Copy Rules

```bash
mkdir -p ~/.roo/rules
cp home/rules/*.md ~/.roo/rules/
```

Files installed:
- `00-identity.md` — core behavior, branching strategy, conventions
- `01-bigmind.md` — BigMind memory discipline (session management, search-first)
- `02-mcp-tools.md` — MCP tool reference (Jira, Confluence, Bitbucket, PDF, etc.)
- `04-visual-verify.md` — visual verification after frontend changes

---

## Step 3: Copy Mode-Specific Rules

```bash
cp -R home/rules-mode-writer ~/.roo/rules-mode-writer
cp -R home/rules-skill-writer ~/.roo/rules-skill-writer
```

These provide XML-based guidance for the mode-writer and skill-writer specialist modes.

---

## Step 4: Copy Skills

```bash
cp -R home/skills ~/.roo/skills
```

13 skills installed:
- `code-review` — structured review against plan
- `create-pr` — Bitbucket/GitHub PR creation
- `create-worktree` — git worktree for ticket work
- `expert-panel-review` — multi-expert plan validation
- `generate-handover` — session/person handover docs
- `generate-solution-doc` — solution documentation + PDF
- `generate-testplan` — structured test plan from implementation plan
- `mvn-test` — Maven test runner (Java)
- `plan-review` — plan quality gate (APPROVED/REVISE)
- `playwright-e2e` — Playwright E2E test infrastructure
- `sprint-report` — Jira sprint status report
- `switch-worktree` — switch VS Code to existing worktree
- `visual-verify` — Playwright visual verification

---

## Step 5: Copy Custom Tools

```bash
cp -R home/tools ~/.roo/tools
cd ~/.roo/tools
npm install
```

15 tools installed:
- `brew_leaves.ts` / `brew_search.ts` — Homebrew utilities
- `context_budget.ts` — token cost estimator
- `git_recent_changes.ts` — structured git log
- `mvn_dependency_tree.ts` / `mvn_test.ts` — Maven helpers
- `pom_inspect.ts` — parse pom.xml to JSON
- `port_watch.ts` — check what's on a TCP port
- `snyk_scan.ts` — security scanning
- `surefire_failures_summary.ts` — test failure parser
- `web_fetch.ts` — lightweight web scraper
- `worktree_list.ts` — git worktree list to JSON
- `hello_test.js` — smoke test tool

**Important:** Run `npm install` in the tools directory — `@roo-code/types` must be installed locally.

---

## Step 6: Configure API Settings

1. Open `roo-code-settings.home.template.json`
2. Replace all `<YOUR_API_KEY_HERE>` with your actual API key
3. Replace all `<YOUR_PROVIDER_BASE_URL>` with your provider URL:
   - Anthropic: `https://api.anthropic.com/v1`
   - OpenRouter: `https://openrouter.ai/api/v1`
   - Ollama: `http://localhost:11434/v1`
4. Update model IDs if using a different provider:
   - OpenRouter: prefix with provider (e.g., `anthropic/claude-sonnet-4`)
   - Ollama: use local model name (e.g., `qwen3:32b`)
5. Import into Roo Code: Settings gear → Import Settings → select the file

### Example: OpenRouter setup

```json
{
  "openAiBaseUrl": "https://openrouter.ai/api/v1",
  "openAiApiKey": "sk-or-v1-your-key-here",
  "openAiModelId": "anthropic/claude-sonnet-4"
}
```

### Example: Ollama (fully local)

```json
{
  "openAiBaseUrl": "http://localhost:11434/v1",
  "openAiApiKey": "ollama",
  "openAiModelId": "qwen3:32b"
}
```

---

## Step 7: Install BigMind (Optional but Recommended)

BigMind provides persistent memory across sessions — it's what makes "Lumen" persistent.

### Option A: Install from source

```bash
cd ~/git  # or wherever you keep repos
git clone <your-bigmind-repo-url> mcp-adp-bigmind
cd mcp-adp-bigmind
uv sync  # or pip install -e .
```

### Option B: Use the existing pi_mcps copy

If you have the pi_mcps repo synced via OneDrive, BigMind is already there.

### Configure BigMind MCP in Roo Code

Add to your MCP server config (`.roo/mcp.json` or VS Code settings):

```json
{
  "mcpServers": {
    "ADP_BigMind": {
      "command": "uv",
      "args": ["run", "python", "-m", "bigmind"],
      "cwd": "<path-to-bigmind>"
    }
  }
}
```

---

## Step 8: Verify Installation

1. Open VS Code
2. Open Roo Code panel (sidebar)
3. Check that custom modes appear in the mode selector (click the mode name):
   - 🪃 Orchestrator
   - 🧩 Skill Writer
   - ✍️ Mode Writer
   - 🛠️ Tool Writer
   - 🎨 Visual QA
4. Try a simple command: type "hello" in Orchestrator mode
5. If BigMind is installed, you should see "🧠 BigMind Session: ..." in the response

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Modes don't appear | Check `~/.roo/.roomodes` exists and is valid JSON |
| Tools don't work | Run `cd ~/.roo/tools && npm install` then "Refresh Custom Tools" in command palette |
| Skills not loading | Verify `~/.roo/skills/<name>/SKILL.md` files exist |
| BigMind connection fails | Check MCP server config, ensure `uv` is in PATH |
| Import fails | Ensure the JSON file has no trailing commas or syntax errors |
| Custom instructions empty | Check settings → Global Instructions after import |

---

## What's NOT Included (Work-Only)

These modes/skills exist in `work/` but are NOT installed on home:
- PAISY-specific modes (planner, jira-ops, reviewer, doc-gen, security-reviewer, plan-reviewer, paisy-cobol)
- COBOL/SSH/domain-specific skills
- ADP Wiki integration rules
- SEC-* security rule references
- German payroll domain memory bank

To add work functionality later, selectively copy from `work/` as needed.