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.