Skip to content

Add Roocode #331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
arnaudgelas wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add Roocode #331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8ac7e5e
feat(converter): align Roo Code bundle with other distributions
arnaudgelas Apr 20, 2026
79a3fd7
feat(roocode): add Roo Code distribution bundle
arnaudgelas Apr 20, 2026
98f1227
feat(cli): add Roo Code scaffolding to arckit init
arnaudgelas Apr 20, 2026
53b115a
feat(copilot): add commands/ directory to extension bundle
arnaudgelas Apr 20, 2026
64cca4e
docs: add Roo Code as seventh distribution format
arnaudgelas Apr 20, 2026
7937e03
docs(book): update distribution count and add Roo Code references
arnaudgelas Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
14 changes: 8 additions & 6 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

## Overview

ArcKit is an **Enterprise Architecture Governance & Vendor Procurement Toolkit** providing 68 slash commands for AI coding assistants (Claude Code, Codex CLI, Gemini CLI, OpenCode CLI) to generate architecture artifacts. It transforms architecture governance from scattered documents into a systematic, template-driven process.
ArcKit is an **Enterprise Architecture Governance & Vendor Procurement Toolkit** providing 68 slash commands for AI coding assistants (Claude Code, OpenAI Codex CLI, Gemini CLI, OpenCode CLI, GitHub Copilot, Roo Code) to generate architecture artifacts. It transforms architecture governance from scattered documents into a systematic, template-driven process.

**Six distribution formats** exist side-by-side in this repo:
**Seven distribution formats** exist side-by-side in this repo:

1. **CLI package** (`src/arckit_cli/`) -- Python CLI installed via `pip`/`uv`, runs `arckit init` to scaffold projects for **Codex CLI** or **OpenCode CLI** (copies templates/commands into them)
1. **CLI package** (`src/arckit_cli/`) -- Python CLI installed via `pip` or `uv`, runs `arckit init` to scaffold projects for **OpenAI Codex CLI**, **OpenCode CLI**, **GitHub Copilot**, or **Roo Code** (copies templates/commands into them)
2. **Claude Code plugin** (`arckit-claude/`) -- Standalone plugin for **Claude Code**, installed via marketplace (`/plugin marketplace add tractorjuice/arc-kit`)
3. **Gemini CLI extension** (`arckit-gemini/`) -- Native extension for **Gemini CLI** with sub-agents, hooks, policies, and GDS theme, published as a separate repo (`tractorjuice/arckit-gemini`) and installed via `gemini extensions install`
4. **OpenCode CLI extension** (`arckit-opencode/`) -- Extension for **OpenCode CLI**, scaffolded via `arckit init --ai opencode`
5. **Codex CLI extension** (`arckit-codex/`) -- Standalone extension for **Codex CLI** with skills, agents, and MCP servers, published as a separate repo (`tractorjuice/arckit-codex`)
6. **Copilot extension** (`arckit-copilot/`) -- Prompt files + custom agents for **GitHub Copilot** in VS Code, scaffolded via `arckit init --ai copilot`
7. **Roo Code bundle** (`arckit-roocode/`) -- `.roomodes`, `.roo/rules/`, and `.roo/skills/` for **Roo Code** in VS Code, scaffolded via `arckit init --ai roocode`

The CLI and plugin have independent version numbers (CLI: `VERSION` + `pyproject.toml`, Plugin: `arckit-claude/VERSION` + `arckit-claude/.claude-plugin/plugin.json`). The Gemini extension version tracks the plugin version (`arckit-gemini/VERSION` + `arckit-gemini/gemini-extension.json`). The OpenCode extension version also tracks the plugin version (`arckit-opencode/VERSION`). The Codex extension version also tracks the plugin version (`arckit-codex/VERSION`). The Copilot extension version also tracks the plugin version (`arckit-copilot/VERSION`). Claude Code support was removed from the CLI in favour of the plugin, which references files in-place via `${CLAUDE_PLUGIN_ROOT}`. The Gemini, OpenCode, Codex, and Copilot extensions are generated by `scripts/converter.py` which rewrites paths, copies supporting files, generates `config.toml` (Codex MCP + agent roles), and rewrites skill command references.
The CLI and plugin have independent version numbers (CLI: `VERSION` + `pyproject.toml`, Plugin: `arckit-claude/VERSION` + `arckit-claude/.claude-plugin/plugin.json`). The Gemini extension version tracks the plugin version (`arckit-gemini/VERSION` + `arckit-gemini/gemini-extension.json`). The OpenCode extension version also tracks the plugin version (`arckit-opencode/VERSION`). The Codex extension version also tracks the plugin version (`arckit-codex/VERSION`). The Copilot extension version also tracks the plugin version (`arckit-copilot/VERSION`). The Roo Code bundle tracks the CLI release and is generated into `arckit-roocode/` from the Claude source set. Claude Code support was removed from the CLI in favour of the plugin, which references files in-place via `${CLAUDE_PLUGIN_ROOT}`. The Gemini, OpenCode, Codex, Copilot, and Roo Code outputs are generated by `scripts/converter.py` which rewrites paths, copies supporting files, generates `config.toml` (Codex MCP + agent roles), and rewrites skill command references.

## Build & Development Commands

Expand Down Expand Up @@ -268,7 +269,7 @@ project/

**Init flags:**

- `--ai codex` / `--ai opencode` / `--ai copilot` - Select AI assistant. `--ai claude` redirects to plugin installation. `--ai gemini` redirects to extension installation.
- `--ai codex` / `--ai opencode` / `--ai copilot` / `--ai roocode` - Select AI assistant. `--ai claude` redirects to plugin installation. `--ai gemini` redirects to extension installation.
- `--minimal` - Skip docs, guides, and reference files
- `--no-git` - Skip git repository initialization
- `--here` - Initialize in current directory
Expand All @@ -295,7 +296,7 @@ project/
2. Create `.arckit/templates/{name}-template.md` with document control section (also copy to `arckit-claude/templates/`)
3. Create `docs/guides/{name}.md` with usage guide (also copy to `arckit-claude/guides/`)
4. If command needs heavy web research (>10 WebSearch/WebFetch calls), also create `arckit-claude/agents/arckit-{name}.md` and make the slash command a thin wrapper that delegates to the agent
5. Run `python scripts/converter.py` to generate Codex Markdown (`.codex/`), OpenCode Markdown (`.opencode/` + `arckit-opencode/`), Gemini extension TOML (`arckit-gemini/`), and Copilot prompts (`arckit-copilot/`)
5. Run `python scripts/converter.py` to generate Codex Markdown (`.codex/`), OpenCode Markdown (`.opencode/` + `arckit-opencode/`), Gemini extension TOML (`arckit-gemini/`), Copilot prompts (`arckit-copilot/`), and Roo Code mode bundles (`arckit-roocode/`)
6. Test plugin: Open a test repo with the plugin enabled and run the command
7. Test CLI: `arckit init test --ai codex --no-git && cd test && codex` (or `--ai opencode`)
8. Update documentation: README.md, docs/index.html, docs/DEPENDENCY-MATRIX.md, CHANGELOG.md
Expand Down Expand Up @@ -410,6 +411,7 @@ Every template must start with a **Document Control** table followed by **Revisi
- `arckit-opencode/VERSION`
- `arckit-codex/VERSION`
- `arckit-copilot/VERSION`
- `arckit-roocode/VERSION`

**Release automation**:

Expand Down
110 changes: 81 additions & 29 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,16 @@ A comprehensive book-length guide to ArcKit — covering every subsystem (comman

### Installation

**ArcKit CLI** (for OpenAI Codex CLI, OpenCode CLI, GitHub Copilot, and Roo Code scaffolding):

```bash
# Install with pip
pip install git+https://github.com/tractorjuice/arc-kit.git

# Or install with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git
```

**Claude Code** (premier experience) — install the ArcKit plugin (requires **v2.1.112+**):

```text
Expand All @@ -70,15 +80,21 @@ Zero-config: all 68 commands, templates, scripts, and bundled MCP servers (AWS K
**GitHub Copilot** (VS Code) — install the ArcKit CLI and scaffold prompt files:

```bash
# Install with pip
pip install git+https://github.com/tractorjuice/arc-kit.git

# Scaffold a project with Copilot prompt files
arckit init my-project --ai copilot
```

Creates `.github/prompts/arckit-*.prompt.md` (68 prompt files), `.github/agents/arckit-*.agent.md` (10 custom agents), and `.github/copilot-instructions.md` (repo-wide context). Invoke commands in Copilot Chat as `/arckit-requirements`, `/arckit-stakeholders`, etc.

**Roo Code** (VS Code) — install the ArcKit CLI and scaffold Roo project files:

```bash
# Scaffold a project with Roo Code mode files and rules
arckit init my-project --ai roocode
```

Creates `.roomodes`, `.roo/rules/`, `.roo/skills/`, and a project README. Open the workspace in VS Code and select an ArcKit custom mode from the Roo Code mode picker.

**Codex CLI** — install the ArcKit CLI:

```bash
Expand All @@ -96,14 +112,16 @@ uvx --from git+https://github.com/tractorjuice/arc-kit.git arckit init my-projec

### Platform Support

| Platform | Claude Code Plugin | Gemini CLI Extension | GitHub Copilot | Codex / OpenCode CLI |
|----------|-------------------|---------------------|----------------|---------------------|
| macOS | Full support | Full support | Full support | Full support |
| Linux | Full support | Full support | Full support | Full support |
| Windows (WSL2) | Full support | Full support | Full support | Full support |
| Windows (native) | Full support | Full support | Full support | Partial |
| Platform | Claude Code Plugin | OpenAI Codex CLI | Gemini CLI Extension | OpenCode CLI | GitHub Copilot | Roo Code |
|----------|-------------------|------------------|---------------------|--------------|----------------|----------|
| macOS | Full support | Full support | Full support | Full support | Full support | Full support |
| Linux | Full support | Full support | Full support | Full support | Full support | Full support |
| Windows (WSL2) | Full support | Full support | Full support | Full support | Full support | Full support |
| Windows (native) | Full support | Partial | Full support | Partial | Full support | Full support |

**Windows users**: The Claude Code plugin, Gemini CLI extension, and GitHub Copilot prompt files work natively on all platforms. For Codex CLI / OpenCode CLI on native Windows (without WSL), some commands containing inline bash snippets may require [Git Bash](https://git-scm.com/downloads/win) or [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). We recommend WSL2 for the best experience.
**Windows users**: The Claude Code plugin, OpenAI Codex CLI, Gemini CLI extension, GitHub Copilot prompt files, OpenCode CLI commands, and Roo Code workspace files work natively on all platforms. For Codex CLI / OpenCode CLI on native Windows (without WSL), some commands containing inline bash snippets may require [Git Bash](https://git-scm.com/downloads/win) or [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). We recommend WSL2 for the best experience.

Roo Code project scaffolding is also available via `arckit init --ai roocode` and uses `.roomodes`, `.roo/rules/`, and `.roo/skills/` in the workspace root.

### Initialize a Project

Expand All @@ -119,6 +137,16 @@ arckit init payment-modernization --ai copilot
arckit init . --ai copilot
```

**Roo Code** (VS Code):

```bash
# Create a new architecture governance project
arckit init payment-modernization --ai roocode

# Or initialize in current directory
arckit init . --ai roocode
```

**OpenCode CLI**:

```bash
Expand Down Expand Up @@ -151,6 +179,11 @@ cd payment-modernization && code .
/arckit-principles Create principles for a financial services company
/arckit-requirements Build a payment processing system...

# Roo Code (VS Code)
cd payment-modernization && code .
# In Roo Code, choose the matching ArcKit mode from the mode picker:
# ArcKit Plan, ArcKit Principles, ArcKit Requirements, etc.

# Codex CLI
cd payment-modernization
codex
Expand All @@ -168,6 +201,8 @@ codex

**GitHub Copilot**: Re-run `arckit init --here --ai copilot` to update prompt files, agents, and instructions.

**Roo Code**: Re-run `arckit init --here --ai roocode` to refresh `.roomodes`, `.roo/rules/`, `.roo/skills/`, and the project README.

**Codex CLI**:

```bash
Expand Down Expand Up @@ -1025,38 +1060,39 @@ Publish all project documentation as an interactive website:
| Assistant | Support | Notes |
|-----------|---------|-------|
| [Claude Code](https://www.anthropic.com/claude-code) | ✅ Premier | **Primary platform.** Plugin with agents, hooks, MCP servers, and auto-updates |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ Full | Extension with commands, MCP servers, and auto-updates |
| [GitHub Copilot](https://github.com/features/copilot) | ✅ Core | VS Code prompt files, custom agents, and repo-wide instructions (`arckit init --ai copilot`) |
| [OpenAI Codex CLI](https://chatgpt.com/features/codex) | ✅ Core | CLI with commands and templates. ChatGPT Plus/Pro/Enterprise ([Setup Guide](.codex/README.md)) |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ✅ Full | Extension with commands, MCP servers, and auto-updates |
| [OpenCode CLI](https://opencode.net/cli) | ✅ Core | CLI with commands and templates |
| [GitHub Copilot](https://github.com/features/copilot) | ✅ Core | VS Code prompt files, custom agents, and repo-wide instructions (`arckit init --ai copilot`) |
| [Roo Code](https://docs.roocode.com/) | ✅ Core | VS Code custom modes, rules, skills, and repo README (`arckit init --ai roocode`) |

> **Platform Support**: ArcKit is developed and tested on **Linux**. Windows has limited support — hooks (session init, project context, filename validation, MCP auto-allow) require bash and jq which are not available on stock Windows. For the best experience on Windows, use a **devcontainer** or **WSL2**.

### Why Claude Code?

Claude Code is the **primary development platform** for ArcKit and provides capabilities not available in other formats:

| Feature | Claude Code | Gemini CLI | Copilot | Codex / OpenCode |
|---------|:-----------:|:----------:|:-------:|:----------------:|
| 68 slash commands | ✅ | ✅ | ✅ | ✅ |
| Templates & scripts | ✅ | ✅ | ✅ | ✅ |
| Bundled MCP servers (AWS, Azure, GCP, DataCommons, govreposcrape) | ✅ | ✅ (3 servers) | — | Manual setup |
| **Autonomous research agents** (10 agents for research, datascout, cloud research, gov code discovery, grants, framework) | ✅ | — | ✅ (10 agents) | — |
| **SessionStart hook** (auto-detect version + projects) | ✅ | — | — | — |
| **UserPromptSubmit hook** (project context injection on every prompt) | ✅ | — | — | — |
| **PreToolUse hook** (ARC filename auto-correction) | ✅ | — | — | — |
| **PermissionRequest hook** (auto-allow MCP documentation tools) | ✅ | — | — | — |
| **Per-command Stop hooks** (output validation, e.g. Wardley Map math checks) | ✅ | — | — | — |
| Wardley Mapping skill (with Pinecone MCP book corpus) | ✅ | — | — | — |
| Mermaid Syntax Reference skill (23 diagram types + config) | ✅ | ✅ | — | ✅ |
| Automatic marketplace updates | ✅ | ✅ | Manual reinstall | Manual reinstall |
| Zero-config installation | ✅ | ✅ | `arckit init` required | `arckit init` required |
| Feature | Claude Code | Gemini CLI | Copilot | Codex / OpenCode | Roo Code |
|---------|:-----------:|:----------:|:-------:|:----------------:|:-------:|
| 68 slash commands | ✅ | ✅ | ✅ | ✅ | ✅ |
| Templates & scripts | ✅ | ✅ | ✅ | ✅ | ✅ |
| Bundled MCP servers (AWS, Azure, GCP, DataCommons, govreposcrape) | ✅ | ✅ (3 servers) | — | Manual setup | — |
| **Autonomous research agents** (10 agents for research, datascout, cloud research, gov code discovery, grants, framework) | ✅ | — | ✅ (10 agents) | — | — |
| **SessionStart hook** (auto-detect version + projects) | ✅ | — | — | — | — |
| **UserPromptSubmit hook** (project context injection on every prompt) | ✅ | — | — | — | — |
| **PreToolUse hook** (ARC filename auto-correction) | ✅ | — | — | — | — |
| **PermissionRequest hook** (auto-allow MCP documentation tools) | ✅ | — | — | — | — |
| **Per-command Stop hooks** (output validation, e.g. Wardley Map math checks) | ✅ | — | — | — | — |
| Wardley Mapping skill (with Pinecone MCP book corpus) | ✅ | — | — | — | ✅ |
| Mermaid Syntax Reference skill (23 diagram types + config) | ✅ | ✅ | — | ✅ | ✅ |
| Automatic marketplace updates | ✅ | ✅ | Manual reinstall | Manual reinstall | — |
| Zero-config installation | ✅ | ✅ | `arckit init` required | `arckit init` required | `arckit init` required |

**Agents** run research-heavy commands (market research, data source discovery, cloud service evaluation) in isolated context windows, keeping the main conversation clean and enabling dozens of WebSearch/WebFetch/MCP calls without context bloat.

**Hooks** provide automated governance: filenames are auto-corrected to ArcKit conventions, project context is injected into every prompt so commands know what artifacts exist, MCP tools are auto-approved, and generated outputs like Wardley Maps are validated for mathematical consistency before being finalized.

Gemini CLI provides a strong experience with all commands and MCP servers but lacks agent delegation and hooks. GitHub Copilot provides all 68 commands as prompt files and 10 custom agents but lacks hooks and MCP servers. Codex CLI and OpenCode CLI provide core command functionality but require manual setup and `arckit init` scaffolding.
Gemini CLI provides a strong experience with all commands and MCP servers but lacks agent delegation and hooks. GitHub Copilot provides all 68 commands as prompt files and 10 custom agents but lacks hooks and MCP servers. Codex CLI and OpenCode CLI provide core command functionality but require manual setup and `arckit init` scaffolding. Roo Code provides custom modes, rules, skills, and a project README, but not the hook and MCP automation that Claude Code ships with the plugin.

### Why Commands, Not Skills

Expand All @@ -1073,7 +1109,12 @@ For GitHub Copilot users in VS Code, ArcKit commands are delivered as prompt fil

```bash
# Install and create project (3 steps, zero config)
# Install with pip
pip install git+https://github.com/tractorjuice/arc-kit.git

# Or install with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

arckit init my-project --ai copilot
cd my-project && code .

Expand All @@ -1091,7 +1132,12 @@ For OpenAI Codex CLI users, ArcKit commands are delivered as skills and auto-dis

```bash
# Install and create project (3 steps, zero config)
# Install with pip
pip install git+https://github.com/tractorjuice/arc-kit.git

# Or install with uv
uv tool install arckit-cli --from git+https://github.com/tractorjuice/arc-kit.git

arckit init my-project --ai codex
cd my-project && codex

Expand Down Expand Up @@ -1445,7 +1491,7 @@ Key references live in `docs/` and top-level guides:

- **Python 3.11+**
- **Git** (optional but recommended)
- **AI Coding Agent**: [Claude Code](https://www.anthropic.com/claude-code) v2.1.112+ (via plugin), [Gemini CLI](https://github.com/google-gemini/gemini-cli) (via extension), [OpenCode CLI](https://opencode.net/cli) (via CLI), or [OpenAI Codex CLI](https://chatgpt.com/features/codex) (via CLI)
- **AI Coding Agent**: [Claude Code](https://www.anthropic.com/claude-code) v2.1.112+ (via plugin), [OpenAI Codex CLI](https://chatgpt.com/features/codex) (via CLI), [Gemini CLI](https://github.com/google-gemini/gemini-cli) (via extension), [OpenCode CLI](https://opencode.net/cli) (via CLI), [GitHub Copilot](https://github.com/features/copilot) (via VS Code), or [Roo Code](https://docs.roocode.com/) (via VS Code scaffolding)
- **uv** for package management: [Install uv](https://docs.astral.sh/uv/)

---
Expand All @@ -1460,6 +1506,9 @@ cd arc-kit
# Install in development mode
pip install -e .

# Or using uv
uv pip install -e .

# Run the CLI
arckit init my-project
```
Expand Down Expand Up @@ -1572,6 +1621,9 @@ ls .github/prompts/arckit-*.prompt.md

# For OpenCode CLI, check if commands directory exists
ls .opencode/commands/

# For Roo Code, check if the workspace files exist
ls .roomodes .roo/rules/
```

**Template not found**: Ensure you've run `/arckit.principles` first
Expand Down
Loading