ground-state

Sub-agent contract

/contract

Constraint: read-only reconnaissance. Surveyors and the synthesizer MUST NOT call edit_file, write_file, or any mutating bash command (no git commit, git push, git checkout, mv, rm, file redirection, package installs, etc.). Read-only tools only: read_file, grep, glob, list_directory, and read-only bash (git status, git log, git diff, cat, ls, find, etc.).

If the survey reveals a fix that's tempting to apply, return it as a recommendation in the snapshot — the orchestrator decides whether to act. Even if the invoking brief sounds prescriptive ("draft the edit", "apply the change"), this skill stops at the snapshot and the preamble artifact. The orchestrator dispatches a separate implementation step afterward.

Before any multi-step implementation (not single-file fixes, not pure Q&A), dispatch three parallel reconnaissance sub-agents, each with a narrow target. Adapt the first two surveyors to the domain:

State surveyor (domain-aware)

Infrastructure surveyor (domain-aware)

When domain is unspecified, infer from the working directory contents.

Memory surveyor Grep the user's auto-memory store (~/.claude/projects/-<cwd-slug>/memory/) + any project CLAUDE.md for keywords from the user's current request. Return relevant memory file pointers with 1-line summaries, or "no relevant memory found."

Synthesize into a 6-line ground-truth snapshot:

• Branch: <current>, <clean|diverged>, upstream: <fresh|stale>
• Recent work: last 3 commits or stash items
• Infrastructure: CI present? package scripts? authoritative configs for this task
• Memory hits: file refs or "none"
• Implementation risks: e.g. "branch is main, don't edit directly"; "CI runs on push"; "memory says prior attempt used approach X"
• Epistemic confidence: <high|medium|low> — based on how much state could be verified. Flag if working directory is sparse, if domain is unfamiliar, or if key artifacts may be missing.

Surface the snapshot and stop. The orchestrator then uses these verified facts — not assumptions — to decide the next step. This skill never edits files.

Wave 4 — Brief Anchor (auto-runs after synthesis)

After the 6-line snapshot is assembled, run a fourth step inline (no additional sub-agent dispatch required): construct the Brief Anchor — a path-verified grounding preamble the orchestrator pastes verbatim into every subsequent sub-agent brief.

Construction procedure:

1. From the state surveyor output, extract the verified cwd (absolute path from pwd), branch (from git symbolic-ref --short HEAD), and HEAD SHA (from git rev-parse HEAD).
2. From the infrastructure surveyor output, extract the 2–4 canonical file paths most relevant to the task (primary config file, main entry point, test root, etc.). For each, run stat <path> — include the path only if stat exits 0. Paths that fail stat are omitted; if zero paths survive, set the list to (none verified).
3. Assemble the preamble block:

## Orchestrator grounding — read this first
- **cwd**: <absolute path>
- **branch**: <branch name>
- **HEAD**: <full SHA>
- **canonical paths** (stat each on entry; emit GROUNDING_FAILED:<path> and abort if missing):
  - <verified_path_1>
  - <verified_path_2>  ← omit line if not applicable

4. Append to the snapshot output under the heading ## Brief Anchor so the orchestrator can copy it directly.

Orchestrator usage contract:

• Prepend the Brief Anchor verbatim to every sub-agent brief that reads files, runs git/gh commands, or references explicit paths. Skip for pure-reasoning tasks (no filesystem reads, no path references).
• Sub-agents receiving the anchor stat each listed path on entry. A missing path returns GROUNDING_FAILED:<path> — the orchestrator re-dispatches once with the corrected path. If the retry also returns GROUNDING_FAILED, emit BRIEF_GROUND_ABORT with both the expected and actual paths plus the corrective command the operator should run — git worktree list to find the intended checkout, then cd <correct-worktree> (or re-invoke the orchestrator from it) — and halt the wave so the operator resolves the worktree mismatch.
• The anchor is session-scoped: one construction pass per ground-state invocation. Do not re-invoke ground-state mid-session to refresh it; instead pass the existing anchor through.

Skip when: Task is Q&A only; single-line fix on an already-identified file; user says "skip pre-flight".