CrewRig

CrewRig is a centralized configuration framework for Gemini CLI, Claude Code, GitHub Copilot CLI, and Antigravity CLI. It serves three complementary purposes:

• Personal context layer — layered configuration files shape how AI assistants behave for a specific user's role, team, and seniority.
• Shared artifact zones — artifacts/ is the single-source zone where skills, agents, and commands are authored once and compiled into outputs for all supported CLIs; an agent source declares what its work needs from a model as a capability profile (spec 0195) rather than naming one — see docs/model-mapping-format.md for what each CLI resolves it to.
• Harness engineering — a built-in feedback loop lets agents tag frictions encountered during real work; the harness curator clusters those frictions into actionable GitHub issues, closing the loop between AI behavior and continuous improvement.

CrewRig develops itself using its own mechanics. The internal agent crew — architect, developer, tester, pr-logbook, and pr-reviewer — runs on the same skills and agents that ship with the framework. The development workflow is the product in action.

Supported Platforms

Platform	Config Target	Setup Command
Gemini CLI	~/.gemini/	task setup-gemini-interactive
Claude Code	~/.claude/rules/	task setup-claude-interactive
GitHub Copilot CLI	Split: .github/copilot/ + .github/skills/ + .github/agents/ (workspace-level)	task setup-copilot-interactive
Antigravity CLI	~/.gemini/config/	task setup-antigravity-interactive

All platforms share the same source configuration files in config/ and artifacts/. Setup and build scripts deploy them into the platform-specific directories. See docs/cli-matrix.md for the full per-CLI integration matrix.

How It Works

Layered Context

Configuration files are organized by priority. Each file addresses a specific concern (identity, policies, expertise, etc.) and they combine to form the agent's full context:

Priority	Source	Purpose
00	config/SOUL.md	Agent identity and values
10	config/level/<LEVEL>.md	Seniority-adapted guidance
20	config/ORGANIZATION.md	Company-wide policies
30	config/PROFILE.md	Personal information
40	config/expertise/<ROLE>.md	Technical specialization
50	config/teams/<TEAM>.md	Team practices and norms
60	artifacts/core/rules/60-tools.md	Memory architecture and core tool rules
65	config/TOOLS.md	Organization-specific tool guidelines

Gemini CLI loads these via numeric-prefix files in ~/.gemini/ with enforced priority order. Claude Code loads them from ~/.claude/rules/ as additive context (all files combine, no override). GitHub Copilot CLI loads them from ~/.copilot/instructions/ as *.instructions.md files, applied to all sessions. Antigravity CLI loads them from ~/.gemini/config/AGENTS.md.

Artifact Zone

artifacts/ is the single-source zone where skills, agents, and commands are written once and compiled into outputs for all CLIs. Contributors edit a single Markdown file with YAML frontmatter; the build step produces Gemini CLI, Claude Code, GitHub Copilot CLI, and Antigravity CLI targets.

Type	Description
Skill	Reusable agent behavior activated via /skill-name
Command	Slash command with a prompt body
Agent	Sub-agent with a dedicated persona
Hook	Lifecycle hook (BeforeTool/AfterTool/etc.)
Policy	Security or behavioral constraint
MCP Server	External tool integration
Theme	UI theme fragment

Install a component on a project:

# Gemini CLI
task install-component TYPE=skills NAME=my-skill

# Claude Code
task install-claude-component TYPE=claude-skills NAME=my-skill

See artifacts/FORMAT.md for the full unified-source specification.

Harness Engineering Loop

The harness turns real-world frictions into shipped improvements through a four-stage loop:

1. Tag — during real work, agents invoke the harness-report skill the moment a friction signal fires (user pushback, tool surprise, process gap). Each tag lands in the MemPalace harness-friction wing.
2. Cluster — task harness-curate -- --apply clusters the tagged frictions by subcategory and opens one descriptive GitHub issue per cluster.
3. Fix — issues are addressed via the normal branch/PR workflow; the internal agent crew handles the implementation cycle.
4. Re-install — after a fix ships, run task build-components and reinstall. The metadata.provenance.version bump in every modified SKILL.md signals that a new version is available.

For automated periodic sweeps, artifacts/library/skills/harness-curator/scripts/schedule-curator.ts installs a macOS launchd job or a Linux crontab entry that runs the curator on a fixed cadence.

Security: Copy by Default

Context files are copied (not symlinked) to the target directory by default. This prevents context poisoning from malicious branches. Symlink mode is available for development only (with a security disclaimer).

Memory Architecture

The framework implements a three-tier memory model:

Tier	System	Role	Access
1	Sequential Thinking	Working memory (ephemeral)	Session only
2	MemPalace	Agent memory (persistent)	Read/write, cross-tool
3	Obsidian	User knowledge (Second Brain)	Read free, write user-controlled

See config/TOOLS.md for the full memory protocol.

Multi-agent concurrency: ChromaDB and MCP daemons

When multiple CLI sessions (Claude Code, Gemini CLI, Copilot CLI, Antigravity CLI) or parallel agents access MemPalace simultaneously, two independent layers each need a single owner, or writes corrupt.

Tier 1 — the ChromaDB daemon. Each PersistentClient instance spawns its own Rust HNSW compactor. Concurrent compactors write to the same binary vector index files without coordination, silently corrupting the HNSW segment — searches return empty results while the SQLite layer remains intact. CrewRig solves this by running a single shared chroma run daemon that owns the PersistentClient. Every CLI session connects through scripts/lib/mempalace-http-wrapper.py, which monkey-patches chromadb.PersistentClient → chromadb.HttpClient before importing MemPalace. See docs/runbooks/chroma-http-server.md for start/stop/status commands, log locations, migration steps, and troubleshooting. The architectural decision is recorded in ADR 0006.

Tier 2 — the shared MemPalace MCP daemon. Collapsing tier 1 does not, on its own, collapse the palace writer lease: each CLI session still ran its own stdio MemPalace process, and the first one to mutate held that lease for the rest of its life, refusing every sibling session with MCP error -32001 ("Peer MCP writer active"). Converting a machine to a single supervised MCP HTTP daemon that every CLI registers against — task mempalace:switch-http — removes that contention between sibling sessions by construction. Every CrewRig setup run defaults a machine to this arrangement: setup probes the daemon, installs and starts it, and registers the HTTP entry without a prompt (spec 0113 delta-02); task mempalace:switch-http remains the machine-wide all-or-nothing converger for machines set up before that change or where one CLI's setup failed. See the runbook for the conversion command, daily operations, and the token-replacement procedure, and ADR 0016 for the decision record.

Adopting CrewRig

Organizations that wish to adopt CrewRig without contributing upstream should follow the Adoption Guide — a step-by-step walkthrough covering fork initialization, overlay configuration, build pipeline, CLI deployment, and upstream synchronization. The guide covers all four supported CLIs (Gemini CLI, Claude Code, GitHub Copilot CLI, Antigravity CLI) and is the primary onboarding surface for adopting organizations.

Lifecycle Scenario

A complete journey, from installing the framework to closing the harness loop:

1. Install — fork crewrig, then run task setup-claude-interactive (or task setup-gemini-interactive). Generate your profile with /init-personal-profile and your soul with /init-soul.
2. Create — add a SKILL.md to artifacts/community/skills/my-skill/, or run task create-extension NAME=my-skill. Run task build-components to generate outputs for both CLIs.
3. Use on another project — install the component: task install-claude-component TYPE=claude-skills NAME=my-skill. The skill is now available in Claude Code on that project.
4. Record frictions — as agents use the skill, they invoke the harness-report skill the moment a recognition signal fires. Each friction tag lands in the MemPalace harness-friction wing.
5. Transform frictions into tickets — run task harness-curate -- --apply. The curator clusters the frictions and opens one GitHub issue per cluster against the target repo.
6. Implement — address the issues via feature branches. The internal agent crew (architect → developer → tester → pr-logbook → pr-reviewer) handles the cycle.
7. Install the new version — run task build-components and reinstall; metadata.provenance.version bumps confirm which components changed.
8. Back to step 3 — use the improved skill on your projects; the harness loop continues.

Prerequisites

Package Managers

OS	Package Manager	Install
macOS	Homebrew	/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Windows	Chocolatey	See install guide
Windows	Scoop	irm get.scoop.sh | iex
Linux	apt / dnf / pacman	Bundled with your distribution

Required Tools

Tool	macOS	Linux (Debian/Ubuntu)	Windows
Gemini CLI	npm i -g @google/gemini-cli	same	same
Claude Code	npm i -g @anthropic-ai/claude-code	same	same
GitHub Copilot CLI	npm i -g @github/copilot	same	same
Antigravity CLI	See Antigravity install (agy)	same	same
Task (3.54 or later, see note below)	brew install go-task	sh -c "$(curl -ssL https://taskfile.dev/install.sh)"	choco install go-task or scoop install task
fzf	brew install fzf	sudo apt install fzf	choco install fzf or scoop install fzf
uv	brew install uv	curl -LsSf https://astral.sh/uv/install.sh | sh	powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
yq	brew install yq	sudo snap install yq	choco install yq

Node.js note: the four setups are TypeScript entries (scripts/setup-<cli>-interactive.ts) and need Node.js 24 or later. The task setup-<cli>-interactive entries run the Node.js floor guard (scripts/lib/node-floor-guard.js) before the entry and stop with a diagnostic below 24. Run by hand, use two separate steps: node scripts/lib/node-floor-guard.js, then node scripts/setup-<cli>-interactive.ts. The setups need neither fzf nor jq and run on Windows without a Bash-compatible shell. The scripts that remain shell scripts still need one (Git Bash, WSL, or MSYS2).

Task note: Task 3.54 or later is required. The tasks live in domain files under taskfiles/ that the root Taskfile.yml includes with the flatten: option, so CI and local runs share one Task version. Every Taskfile declares version: '3.54', so an older Task fails loudly instead of silently renaming tasks.

Quick Start

Gemini CLI

git clone [email protected]:crewrig/crewrig.git
cd crewrig

# Generate your personal profile
gemini "/init-personal-profile"

# Customize the agent identity
gemini "/init-soul"

# Run the interactive setup (deploys to ~/.gemini/)
task setup-gemini-interactive

Claude Code

git clone [email protected]:crewrig/crewrig.git
cd crewrig

# Generate your personal profile
claude /init-personal-profile

# Customize the agent identity
claude /init-soul

# Run the interactive setup (deploys to ~/.claude/rules/)
task setup-claude-interactive

Copilot CLI

git clone [email protected]:crewrig/crewrig.git
cd crewrig

# Generate your personal profile
copilot -i "/init-personal-profile"

# Customize the agent identity
copilot -i "/init-soul"

# Run the interactive setup (deploys to ~/.copilot/)
task setup-copilot-interactive

Antigravity CLI

git clone [email protected]:crewrig/crewrig.git
cd crewrig

# --new-project anchors the session to this clone — without it, on a machine
# with other Antigravity projects, agy resolves against whichever project was
# last active instead of the current directory.

# Generate your personal profile
agy -i "/init-personal-profile" --new-project

# Customize the agent identity
agy -i "/init-soul" --new-project

# Run the interactive setup (deploys to ~/.gemini/config/)
task setup-antigravity-interactive

What happens step by step

1. /init-personal-profile walks you through an interview to generate config/PROFILE.md with your identity, tooling preferences, projects, and working philosophy.
2. /init-soul lets you customize the agent's personality by refining the config/SOUL.md template section by section.
3. task setup-*-interactive copies shared configuration files to the target directory, then prompts you to select your team, expertise, and experience level through numbered questions (?N previews entry N).

Artifact Zone (optional)

The artifacts/ directory is the single-source zone for lightweight, prompt-based components. Single-source files generate outputs for all supported CLIs:

Gemini CLI:

task install-workspace
task install-component TYPE=skills NAME=my-skill

Claude Code:

task install-claude-workspace
task install-claude-component TYPE=claude-skills NAME=my-skill

Build from source:

task build-components           # Both tools
task build-components-gemini    # Gemini only
task build-components-claude    # Claude Code only
task check-components           # Drift detection (CI)

Extensions (optional)

Extensions are code-based capabilities (TypeScript MCP servers) packaged as independent npm modules. From a single extension.json manifest, the shared render produces the tool-native form for all four supported command-line tools (Gemini CLI, Claude Code, GitHub Copilot CLI, Antigravity CLI):

All CLIs (umbrella installer):

task install-deps
task install-extension-all EXT=hello-world

Gemini CLI:

task install-deps
task install-gemini-extensions
task install-gemini-extension EXT=hello-world

Claude Code:

task install-deps
task build-claude-plugin EXT=hello-world
task install-claude-plugin EXT=hello-world

See Extension authoring for the authoring model, extensions/core/hello-world/ for a complete example, extension-skeleton/EXTENSION-FORMAT.md for the manifest specification, and extension-skeleton/ as a starting template.

Repository Structure

extensions/                # Extension registry, segmented into three tiers
├── core/                  # Upstream-shipped extensions (synced, strict)
│   └── hello-world/       # Example extension (MCP server + command + skill)
├── library/               # Upstream harness/shared extensions (synced, strict)
└── org/                   # Adopter-owned extensions (excluded from sync)

extension-skeleton/        # Template for new extensions
├── EXTENSION-FORMAT.md    # extension.json specification
├── agent/
├── base/
├── command/
├── hook/
├── mcp-server/
├── skill/
└── theme/

config/
├── gemini/
│   └── settings.json      # Gemini CLI settings and MCP servers
├── claude/
│   └── settings.json.template
├── level/                 # INTERN, JUNIOR, CONFIRMED, EXPERT
├── expertise/             # BACKEND-JAVA, FRONTEND-REACT, FULLSTACK-PYTHON,
│                          # DEVOPS-CLOUD, QA-AUTOMATION, PRODUCT-OWNER
├── teams/                 # ATLAS, NOVA, FORGE, SENTINEL, HORIZON
├── ORGANIZATION.md        # Company-wide policies
├── PROFILE.md.template    # Personal profile template
├── SOUL.md.template       # Agent identity template
├── TOOLS.md               # Memory architecture and MCP server guidelines
└── release-monorepo.json  # Monorepo release configuration

artifacts/
├── FORMAT.md              # Unified source format specification
├── core/                  # Upstream-owned SDLC lifecycle tools and role skills/agents
│   ├── skills/            # Reusable agent skills — SDLC + role skills
│   │   ├── spec-author/   # Lifecycle: qualification stage author
│   │   ├── pr-logbook/    # Lifecycle: PR and logbook composer
│   │   ├── pr-reviewer/   # Lifecycle: independent PR reviewer + linters
│   │   │   └── scripts/   # lint-markdown.ts, lint-skill.ts, ...
│   │   └── # … 10 role skills (architect, astro, copywriting, developer, doc-writer,
│   │       # frontend, github-actions, security, tester, web-tester)
│   └── agents/            # Sub-agent definitions (lifecycle + role agents)
│       └── # … spec-author, pr-logbook, pr-reviewer, architect + 17 role agents
├── library/               # Upstream-owned harness machinery (user-home scope)
│   ├── skills/
│   │   ├── harness-report/    # Skill: tag frictions during real work
│   │   └── harness-curator/   # Skill: cluster frictions and open GitHub issues
│   │       └── scripts/       # schedule-curator.ts, curate.ts, ...
│   └── agents/
│       └── harness-curator/   # Agent: curator specialist
├── community/             # Adopting organisation sandbox
│   ├── skills/            # Org-authored role skills (not yet validated)
│   ├── agents/            # Org-authored agents (not yet validated)
│   ├── commands/          # Org-specific slash commands
│   ├── hooks/             # Org-specific lifecycle hooks
│   ├── policies/          # Org-specific policy files
│   ├── mcp-servers/       # Org-specific MCP server configurations
│   └── themes/            # Org-specific UI themes
└── org/                   # Adopting organisation validated components
    ├── skills/
    └── agents/

.gemini/                              # Build output — generated by scripts/build-components.ts
                                      # Do not edit manually
.claude/                              # Build output — generated by scripts/build-components.ts
                                      # Do not edit manually

hooks/                                # Shared hook scripts
├── mempalace-transcript.ts           # Session recording (opt-in; Node.js >= 24 when it fires)
├── gemini-transcript-hooks.json      # Gemini hook registration
└── claude-transcript-hooks.json      # Claude Code hook registration

docs/
└── scripting-conventions.md          # Shell scripting standards

tests/
└── e2e/                              # End-to-end test documentation

.github/workflows/                    # CI/CD pipelines
├── build.yml                         # Component build and drift check
├── claude.yml                        # Claude Code integration
├── pages.yml                         # GitHub Pages deployment
├── release-monorepo.yml              # Monorepo release automation (also packages and publishes each extension's release artifact, spec 0183)
├── scripting-conventions.yml         # Shell scripting lint
└── security-mcp.yml                  # MCP security scan

scripts/
├── build-components.ts               # The TypeScript build
├── build-claude-plugin.ts            # Shim: forwards to build-claude-plugin.ts (the TypeScript plugin generator)
├── check-skill-versions.ts           # CI gate: enforces version bump on modified sources
├── create-extension.ts               # Shim: forwards to create-extension.ts (the TypeScript extension scaffolder)
├── migrate-extension.ts              # Shim: forwards to migrate-extension.ts (converts an extension off the retired declaration shape, spec 0183)
├── import-claude-history.ts          # Claude transcript import
├── import-gemini-history.ts          # Gemini transcript import
├── install-claude-plugin.ts          # Shim: forwards to install-claude-plugin.ts (Claude Code plugin installer)
├── install-extension.ts              # Shim: forwards to install-extension.ts (Gemini extension installer)
├── install-extension-all.ts          # Shim: forwards to install-extension-all.ts (cross-CLI umbrella extension installer)
├── install-workspace.ts              # Shim: forwards to install-workspace.ts (bulk Gemini component install)
├── link-extensions.ts                # Shim: forwards to link-extensions.ts (symlink extensions for local dev)
├── manage-claude-component.ts        # Shim: forwards to manage-claude-component.ts (Claude Code component manager)
├── manage-workspace-component.ts     # Shim: forwards to manage-workspace-component.ts (Gemini component manager)
├── monorepo-release.ts               # Shim: forwards to monorepo-release.ts (monorepo release driver — bumps versions, calls release-package-extension.ts, publishes the release (GitHub: through a release PR, docs/github-release-pr.md))
├── release-package-extension.ts      # Shim: forwards to release-package-extension.ts (the ONE place a release artifact's shape is decided: renders, asserts, archives; spec 0183)
├── release-pr.ts                     # Opens/updates/closes the GitHub release PR and dispatches its required checks (issue #1379)
├── package-extension.ts              # Shim: forwards to package-extension.ts (manually package a single extension at its current committed version)
├── package-extensions.ts             # Shim: forwards to package-extensions.ts (manually package every extension)
├── prune-transcripts.ts              # Remove old transcript archives
├── setup-claude-interactive.ts       # Shim: forwards to setup-claude-interactive.ts (Claude Code setup, interactive)
├── setup-gemini-interactive.ts       # Shim: forwards to setup-gemini-interactive.ts (Gemini CLI setup, interactive)
├── unlink-component.ts               # Shim: forwards to unlink-component.ts (remove a component symlink)
├── unlink-extensions.ts              # Shim: forwards to unlink-extensions.ts (remove all extension symlinks)
├── lib/
│   └── mempalace-pin.json            # Single source of the MemPalace version pin (the shell libraries were retired in #1344)
└── tests/
    ├── governance-suite-skill-versions.test.ts       # Tests for check-skill-versions (cases 4-7)
    ├── governance-suite-skill-versions-base.test.ts  # Tests for check-skill-versions (base-ref cases)
    └── (frontmatter-fence tests are node --test files: build-components-frontmatter-fence.test.ts)

Taskfile.yml                          # Task runner root (default task, global vars, includes)
taskfiles/                            # Domain Taskfiles included by the root (setup, extensions, lint, e2e, ...)
AGENTS.md                             # Agent working rules
CLAUDE.md                             # Claude Code entry point (@AGENTS.md)
CONTRIBUTING.md                       # Contribution guide
DEVELOPMENT.md                        # Extension development guide
crewrig.config.toml                   # CrewRig framework configuration
package.json                          # Node.js workspace manifest
renovate.json                         # Renovate dependency-update configuration

MCP Servers

Gemini CLI (config/gemini/settings.json)

• MemPalace — Unified agent memory (replaces KG Memory + Deep Memory).
• Sequential Thinking — Working memory for structured reasoning.

Claude Code (~/.claude.json, managed by claude mcp add)

Claude Code reads MCP servers from ~/.claude.json, not from any mcp.json file. The setup-claude-interactive.ts entry registers them via claude mcp add --scope user. To inspect or manage them later:

claude mcp list                      # Show registered servers
claude mcp add --scope user <name> -- <command> [args...]
claude mcp remove <name>

• Sequential Thinking — Working memory; registered as user-scope.
• MemPalace — Persistent agent memory; registered as user-scope (the setup script auto-detects the right Python interpreter and verifies the installed version is within the supported range >=3.6.0,<3.7). Install or upgrade with task install-mempalace (or pipx install --force 'mempalace>=3.6.0,<3.7'). Session recording, an opt-in of each setup script, wires hooks/mempalace-transcript.ts by its absolute path in the checkout that ran setup (no copy under the CLI's home, no jq or curl). It needs Node.js 24 or later when the hook fires, and re-running setup from the checkout repairs a moved one (docs/cli-matrix.md row 8b).
• GitHub — Available via Claude Code's built-in connectors.

Contributing

All contributions go through feature branches merged into main via Pull Request. See CONTRIBUTING.md for the full guide, DEVELOPMENT.md for the extension development lifecycle, and AGENTS.md for commit conventions (Gitmoji), PR format, and logbook issue requirements.