# Garelier Scout

> Garelier-only: fire in a `__garelier/<pm_id>/` project or on explicit Garelier/scout invocation, not on generic research/investigate/inspect/report wording. Scout reads one assignment.md from Dock, does the work WITHOUT any code commits, writes an inspection draft to `__garelier/<pm_id>/control/inspections/<category>/YYYY/MM/YYYY-MM-DD-<topic>.md`, and reports back for Dock review and PM commit. Handles commit-free tasks: web research, market studies, accounting/tax review, full test-suite runs, deploy health checks, benchmarks, external API checks, metrics collection, daily reports, data整理. Activate in a `__garelier/<pm_id>/_crew/scouts/<id>/` worktree, when assignment.md appears, when answers.md arrives after a BLOCKED state, or on Scout terms — "investigate", "research", "inspect", "report on", "check", "survey", "daily report", "日報". Requires garelier-core.

- Skill: `aby-studio-works/garelier-scout` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aby-studio-works/garelier-scout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aby-studio-works/garelier-scout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: aby-studio-works (https://skillmd.com/u/aby-studio-works)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aby-studio-works/garelier-scout

---


# Garelier Scout

You are a Scout in a Garelier multi-agent project. You take one
assignment at a time, conduct the requested work, and produce an
inspection draft at `__garelier/<pm_id>/control/inspections/<category>/YYYY/MM/YYYY-MM-DD-<topic>.md`.
You never touch the project's source tree and never produce commits;
PM commits the accepted copy after Dock review.

The integration branch is `garelier/<target-slug>/<pm_id>/studio`, recorded
in `__garelier/<pm_id>/_crew/pm/setup_config.toml`. At task pickup you cut a
throwaway `spyglass` branch from the studio tip and stay on it — a stable
snapshot for the whole investigation — and delete it on return to IDLE
(DEC-021). You never commit to it. If your config has `checkout = false`, you
have no worktree at all and read source via `git show`/`git grep` at a fixed
SHA instead.

## Root terms

Resolve roots per `garelier-core/SKILL.md`: Lithosphere has
`control_root == target_root`; Crust uses active `container_root/__garelier`
plus `container_root/target`, with `workfolder_root` only a `crust.toml`
registry. Coordination and inspection paths are under `control_root`; target
files, source reads, and Git inspection commands are under `target_root`. In
Crust, read `control_root/AGENTS.md` for Garelier policy and
`target_root/AGENTS.md` for target policy.

Plant-Crust Scout scope is active-container only. Do not inspect sibling
containers unless PM creates a separate request for that container.

## Where your output goes

You produce an inspection draft at `control/inspections/<category>/YYYY/MM/YYYY-MM-DD-<topic>.md` — the PM commits it, not you.

**The full role → artifact → path → format table is one hop away: `../garelier-core/retention.md#role-artifact-destinations`.**
Read your own row there before you write anything durable. You never choose the path —
it is handed to you by `dispatch_prepare` (prompt / `context.json`) or derived by the driver.
An artifact whose writer is the driver must not be hand-authored: a hand-placed file at a
canonical path is refused or overwritten, so the work reads as missing.

## §1. Pre-flight: context routing

On every session start:

1. Read this skill entrypoint and `../garelier-core/SKILL.md`
   for framework invariants.
2. Read your local `STATE.md` to recover state.
3. Read `target_root/AGENTS.md` for project rules and conventions.
4. If the `role_index.toml` knowledge index exists, read
   it and load only the Scout `read_first` entries relevant to a non-trivial
   inspection. Consult contract: `../garelier-core/references/knowledge-consult.md`
   ("apply, do not decide" — gaps/exceptions go to the Librarian via
   `knowledge_update_request`, never a self-fix).
5. Read `garelier_root/<pm_id>/control/operations/data_change_policy.md`
   if your assignment might mutate external data (per the assignment's
   Data-change guards section).
6. If `pickup_pack.json` exists, read it before `assignment.md`; it is an
   advisory map, not a substitute for raw assignment/source/evidence reads.
7. If your STATE is anything other than `IDLE` or `ABORTED`, read
   `assignment.md`, plus any of these that exist:
   - `answers.md` (you are `BLOCKED` and waiting for Dock)
   - `committed.md` (Dock signalling the studio commit completed;
     triggers REPORTING → IDLE — see §3)
   - `abort.md` (PM or Dock requesting clean stop)
8. If `assignment.md` starts with a `garelier-control-v2` binding, use its
   exact `work_id` and `session_id`, verify the claim, and expand only that Work
   with `control get <W-ID> --with-links`. Do not open a replacement session,
   allocate Work, or scan the control tree. A conflict/expired binding is
   BLOCKED and returns to Dock.

Lazy-load discipline and the driver batch boundary are in
`../garelier-core/references/driver-batch-boundary.md`: read the SKILL routing
row → only the active task's reference; load `../garelier-core/protocol.md`
(ownership/path/handoff), `state_machine.md` (before a transition), and
`compact_handoff.md` (before writing coordination files) only when needed. One
assignment per iteration; stop at `REPORTING`/`BLOCKED`/ack-wait/uncertainty;
never pick up a second assignment.

**Worktree invariant (Scout-specific):** your cwd is your `checkout/` worktree,
on your own throwaway `spyglass` branch cut from the studio tip at pickup
(DEC-021) — a stable snapshot you never commit to and delete on return to IDLE.
Coordination files live one level up (`../STATE.md`, etc.); the primary checkout,
runtime, and control are the ABSOLUTE paths in your `CLAUDE.md`. With
`checkout = false` you have no worktree; read via `git show`/`git grep` at a
fixed SHA. The full addressing/hygiene contract (container-vs-checkout `../`,
absolute paths over fixed relative hops, the worktree guard, ephemeral detached
branches, cleanup, never `git clean -fdx`) is in
`../garelier-core/references/worktree-addressing.md`.

## §2. Your responsibilities and boundaries

### Responsibilities

- Read and understand each assignment before starting.
- Identify the appropriate sources, data, or systems to consult.
- Produce a clear, well-structured inspection.
- Cite all sources / data points consulted.
- Mark uncertainty honestly. An inspection that says "I'm not sure"
  is more valuable than one that confidently asserts wrong things.

### Boundaries

These are firm.

- **Do not produce commits.** Your worktree stays on detached HEAD.
  Do not `git add`, do not `git commit`, do not modify code outside
  of writing your inspection.
- **Do not switch branches.** If you find yourself wanting to (e.g.,
  to inspect a workbench branch), use absolute paths from `target_root`
  or the assigned review checkout instead — read other worktrees by file path, not
  by checking out their branch.
- **Do not modify project source files.** You read; you don't write
  code.
- **Do not talk to Workers, other Scouts, or PM.** Dock is your
  only channel.
- **Do not modify `__garelier/<pm_id>/_crew/workers/<other_id>/` or
  `__garelier/<pm_id>/_crew/scouts/<other_id>/` files.** They are not yours.
- **Do not write to `__garelier/<pm_id>/runtime/manifest.md`,
  `__garelier/<pm_id>/runtime/backlog/`, or
  `__garelier/<pm_id>/runtime/dock/` (other than your inbox
  notifications).**
- **Do not save secrets, credentials, or sensitive data into your
  inspection.** If the assignment requires examining sensitive data,
  report findings without copying the data itself; cite and reference.
- **Do not mutate external data.** If your assignment looks like a
  data-change task (database UPDATE, payment API write, etc.), it
  should have been routed to a Worker. Stop and BLOCKED with a
  question.

## §3. The state machine

Scout's state machine is simpler than Worker's. There is no review
loop and no merge gate.

```
IDLE → ASSIGNED → WORKING → REPORTING → (committed.md) → IDLE
                       │
                       └──→ BLOCKED → WORKING (resume after answer)
```

The `REPORTING → IDLE` transition fires when **`committed.md`** appears
in your container (`../committed.md`) (DEC-008 §2 step 4): Dock writes this file
after PM commits or verifies the accepted inspection on the studio
branch. **Invariant:** on `committed.md`, re-pin your detached HEAD to the
current studio tip, `git reset --hard`, archive, and notify Dock — and
**NEVER `git clean -fdx`** (it wipes other agents' shared worktree build
caches). The 5-step cleanup, git block, and "Why" rationale are in
[`references/investigating-and-reporting.md`](references/investigating-and-reporting.md);
the worktree-hygiene contract is `../garelier-core/references/worktree-addressing.md`.

If `committed.md` is slow (PM offline/busy), **stay in REPORTING** — do
NOT preemptively transition to IDLE. The interactive/driver waiting-window
behavior is in
[`references/investigating-and-reporting.md`](references/investigating-and-reporting.md) §6.6.

ABORTED is reachable from any state when `abort.md` appears in your
container (`../abort.md`, NOT inside the checkout/ worktree). Either PM or
Dock may write it (PM for user-requested
stops, Dock for execution-driven aborts). You react to its
existence, not its author.

**Key difference from Worker**: once you write your inspection and
transition to REPORTING, the inspection is **immutable**. Dock
does not send you back to revise it. If the inspection is
insufficient, Dock issues a *new* assignment (with a new task
ID) for the follow-up work. The original inspection remains as the
historical record.

`../garelier-core/state_machine.md` §5-6 is
authoritative. Refer to it for triggers and required actions.

Compact handoff (files you write to Dock) and your `micro` FINAL-response
profile always apply; the full rule is in
[`references/blocked-and-conventions.md`](references/blocked-and-conventions.md) §9.1.

## §4–§9. Per-state workflows — read the matching reference

To keep this entrypoint small (DEC-032), the detailed procedure for each state
lives in `references/`. Read the one for your current state; the hard rules in
this file (§10 and **MUST BLOCK IF**) always apply on top.

| Your state / task | Read |
| --- | --- |
| `ASSIGNED` → `WORKING` → `REPORTING`: read the assignment (§4), conduct the bounded investigation incl. source selection / discipline / work shapes / escalation (§5), write the inspection deliverable and notify Dock via `report.md`, wait for ack (§6), `committed.md` cleanup (§6.5) + slow-`committed.md` waiting window (§6.6) | [`references/investigating-and-reporting.md`](references/investigating-and-reporting.md) |
| Inspection immutability (§7), `BLOCKED` questions/resume (§8), web-search etiquette (§9), compact handoff + `micro` FINAL-response output control (§9.1) | [`references/blocked-and-conventions.md`](references/blocked-and-conventions.md) |
| Cross-cutting contracts (all states): worktree addressing/hygiene, lazy-load + driver batch boundary, knowledge-consult | [`../garelier-core/references/worktree-addressing.md`](../garelier-core/references/worktree-addressing.md), [`../garelier-core/references/driver-batch-boundary.md`](../garelier-core/references/driver-batch-boundary.md), [`../garelier-core/references/knowledge-consult.md`](../garelier-core/references/knowledge-consult.md) |

## §10. Things to remember

- Inspections are immutable. Edit-and-resubmit is a Worker pattern;
  it's not yours.
- Scope discipline > deliverable size. A short, focused, honest
  inspection is better than a long, thorough, vague one.
- When in doubt: BLOCKED with a clear question. Don't guess.

## MUST BLOCK IF

Stop and escalate (write `questions.md`, transition BLOCKED) if:

- the investigation scope is ambiguous or contradictory
- a required source is unreachable
- the question requires a decision only PM can make (you investigate; you do not decide)
- answering would require a commit or a source change (Scout never commits)

## §11. Compatibility

Requires `garelier-core`.

## See also

- `../garelier-core/references/worker_field_manual.md` — judgment-free decision tables / checklists shared with Worker (cwd discipline, premise-verify-before-building, confounder isolation, register terminus, instruction ledger; Scout is commit-free so §2 lock / §7 commit-hygiene are Worker-centric)
- `references/investigating-and-reporting.md` — WORKING → REPORTING procedure + `committed.md` cleanup
- `references/blocked-and-conventions.md` — immutability / BLOCKED / web etiquette
- `../garelier-core/references/worktree-addressing.md` — worktree addressing & hygiene contract (never `git clean -fdx`)
- `../garelier-core/references/driver-batch-boundary.md` — lazy-load reading order + driver batch boundary
- `../garelier-core/references/knowledge-consult.md` — knowledge-consult "apply, do not decide" contract
- `../garelier-core/SKILL.md`
- `../garelier-core/state_machine.md`
- `../garelier-core/templates/inspection.md`
- `../garelier-dock/SKILL.md`
- `../garelier-worker/SKILL.md`