CrewRig

Core concepts

This page introduces the six concepts that recur throughout CrewRig at a conceptual level. Each links to the detailed documentation that specifies it normatively; the goal here is shared vocabulary, not exhaustive coverage.

The layered context system

An AI assistant's behavior is shaped by a stack of context files, each addressing one concern and combined in a fixed priority order. CrewRig organizes them with a numeric prefix from 00 to 65:

Priority Source Concern
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

The four supported tools consume the same source files but load them differently: Gemini CLI uses numeric-prefix files in ~/.gemini/ with enforced priority order, Claude Code combines them additively from ~/.claude/rules/, GitHub Copilot CLI applies them as *.instructions.md files in ~/.copilot/instructions/, and Antigravity CLI loads them from ~/.gemini/antigravity-cli/. The build pipeline that reconciles these differences is documented in the CLI support matrix.

Core, overlay, and examples layering

Every path in the repository belongs to exactly one of three layers, which governs who owns it and how an upstream synchronization treats it:

  • core — owned by the upstream CrewRig project. Adopting organizations do not modify these paths; upstream updates land here cleanly.
  • overlay — owned by the adopting organization. Upstream updates never touch these paths.
  • examples — illustrative templates the upstream project ships. An organization may copy and adapt them, but is not expected to extend them in place.

This boundary contract is what lets an organization fork CrewRig, customize its own surface, and still pull upstream improvements without merge conflicts. The authoritative classification of every path — including the adopt-on-edit policy for catalogs like config/expertise/ and config/teams/ — lives in the Layer taxonomy and boundary contract.

Multi-CLI parity

CrewRig implements each feature symmetrically across Gemini CLI, Claude Code, GitHub Copilot CLI, and Antigravity CLI. Silent asymmetry is prohibited: where a feature cannot be mirrored on a given tool, the gap must be justified with concrete evidence that the target tool lacks the mechanism, rather than left unexplained. The per-tool integration points, parity checks, and gap-acceptance evidence are tracked in the CLI support matrix.

The CLI-agnostic model declaration

An agent source declares what its work needs from a model as a capability profile, carried in the source under metadata.model: — never a concrete model, a vendor, or a CLI-namespaced key.

A per-target mapping decides what that profile resolves to on each of the four supported command-line interfaces, and the build performs that resolution when components are compiled, per spec 0198.

A resolution never fails a build; when a target cannot serve what the profile asks for, it records what it could not serve instead, per spec 0197.

The compiled Claude Code agent output is one flat file per agent, per spec 0201.

The declaration itself is detailed in Authoring skills, agents & commands, and the mapping format each target's resolution follows is normative in the model-mapping format reference.

Shared cross-tool memory

CrewRig uses a three-tier memory model so that knowledge an agent builds up persists and travels across tools:

Tier System Role Persistence
1 Sequential Thinking Working memory (ephemeral) Session only
2 MemPalace Agent memory (persistent) Cross-session, cross-tool
3 Obsidian User knowledge base Read free, write user-controlled

MemPalace is the tier that makes memory shared: it is read/write and visible across Gemini CLI, Claude Code, Copilot CLI, and Antigravity CLI, so a decision recorded during a Claude Code session can be recovered later from Gemini CLI. Under the shared MemPalace MCP HTTP daemon topology, the agent-memory tier is served by a single shared process rather than by one process per session — see ADR 0016 for the decision record and the MCP daemon runbook for converting a machine to it. The full memory protocol — how agents activate memory at session start, the wing/room/drawer structure, and the cross-tool task-handoff convention — is specified in the framework's tool rules (the priority-60 core rules file).

The harness feedback loop

The harness turns frictions agents hit during real work into tracked improvements. When a recognition signal fires (for example, the user reverts the agent's action, or a tool surprises the agent a second time), the agent invokes the harness-report skill to tag the friction into a global memory wing. The harness-curator skill later clusters those tags and opens one descriptive GitHub issue per cluster, which is then fixed through the normal branch/PR workflow. Where that issue lands depends on the component's tier: frictions on upstream-owned components (core, library) always reach the upstream repository, while frictions on a fork's own components (community, org) land on the fork's configured feedback_repo. The loop is covered in depth on the Harness engineering page.