Garelier Core

Garelier Core

This skill is the shared reference library for the Garelier multi-agent coordination framework. The role skills (garelier-pm, garelier-dock, garelier-worker, garelier-scout, garelier-smith) each declare a dependency on the definitions in this skill. This file is a lean index: the detail lives in the companion docs (protocol.md, state_machine.md, …) and in references/ (DEC-034). Open the one you need; do not bulk-load everything.

Root terms

• control_root: the root that owns __garelier/.
• garelier_root: control_root/__garelier.
• target_root: the target project Git root.
• Plant-Lithosphere: control_root == target_root.
• Plant-Crust: control_root != target_root; the active container owns __garelier/, and target_root is normally container_root/target. workfolder_root is only the crust.toml registry and does not own workfolder_root/__garelier.

Garelier control/runtime paths are relative to control_root. Target project files, Git operations, worktrees, and quality gates are relative to target_root or a checkout created from it. In Plant-Crust, target_root/__garelier is forbidden.

Plant-Crust cross-container rule: PM may read registered containers and write per-container Dock requests; Dock and all subordinate roles are active-container scoped and must not read or write sibling containers.

When you are reading this

You are operating in a Garelier project. A role-specific skill is your primary instruction source. This skill provides the framework's shared definitions that those role skills rely on:

• File-based message protocol (protocol.md)
• Compact handoff rules (compact_handoff.md)
• Output control for provider final responses (output_control.md)
• State machine for Worker, Smith, and Scout (state_machine.md)
• Retention rules for daily/high-volume operation (retention.md)
• Persistent project-management rules (control_contract.md)
• Plan-graph control lifecycle (control session-open/resume/get, Backlog and Checkpoint claims, revision-checked transaction, strict doctor/reconcile); only schema 3 plan_graph_markdown is accepted
• Templates for every Garelier file format (templates/), including compact JSON sidecar summaries for selected Markdown deliverables.

Reading order

When a role skill instructs you to "consult garelier-core", read in this order, stopping when you have what you need:

0. correct_operation.md — the contract for whether you worked correctly (role boundary, allowed paths, owned branch, legal transition, evidence, escalation). It governs everything below: a finished deliverable that broke a boundary or approval is a failure, not a success (governed autonomy, DEC-023).
1. protocol.md — canonical when you need exact paths in __garelier/, who owns each file, or how messages are formatted.
2. compact_handoff.md — required before writing role-to-role runtime state. Garelier keeps internal handoff compact by default.
3. output_control.md — how to keep your provider FINAL response short (durable detail goes to official files) without shortening code / paths / SHAs or hiding risks, warnings, or required approvals.
4. state_machine.md — required when transitioning state (e.g., a Worker completing a task, a Scout entering BLOCKED, a Dock reviewing).
5. retention.md — required when rotating history, writing high-volume inspections, or pruning runtime archives.
6. control_contract.md — required when managing, importing, exporting, or validating persistent control/ authority. It is a compact router: resolve the exact schema/storage pair, reject schemas 1 and 2, then read plan_graph_contract.md (v3).
7. templates/<name> — required when creating any Garelier file. Always start from the template; never invent the format.

protocol.md and state_machine.md are the canonical sources when their topics are needed. They are not a mandate to bulk-load every full reference on every role iteration when the driver prompt supplies the applicable compact contract. When a matching JSON sidecar template exists (report.json, review.json, guardian_report.json, concierge_report.json, inspection.json), keep the Markdown artifact as the official human-readable record and write the compact sibling JSON summary too. The JSON sidecar is for fast routing/status only; do not duplicate the Markdown body inside it.

Reference routing

The framework-invariant detail that used to live inline now sits in references/ (moved verbatim, DEC-034). Open the one your task needs:

protocol.md remains canonical for the full path / ownership matrix and the branch push policy when those details are needed — the references give orientation, protocol.md governs.

Vocabulary

Garelier uses its own vocabulary that does NOT overlap with git-flow naming. Use the canonical terms; do not introduce the deprecated ones in new content.

See also

• references/branches-and-layout.md, references/roles-and-lanes.md, references/execution-and-operations.md
• references/worktree-addressing.md — shared worktree addressing/hygiene contract (container vs checkout/, pre-edit guard, ephemeral branches, cleanup; never git clean -fdx)
• references/knowledge-consult.md — shared "apply, do not decide" knowledge-consult contract (role_index read_first, the knowledge trees, knowledge_query; DEC-029)
• references/driver-batch-boundary.md — shared lazy-load reading order + driver batch boundary (one assignment per iteration)
• Companion docs: protocol.md, state_machine.md, compact_handoff.md, output_control.md, retention.md, control_contract.md, correct_operation.md, templates/
• ../garelier-pm/SKILL.md, ../garelier-dock/SKILL.md, ../garelier-worker/SKILL.md, ../garelier-scout/SKILL.md
• Repository documentation: <garelier-repo>/docs/
• DECs: DEC-001, DEC-002, DEC-003, DEC-034