agent-afk 5.127.2 → 5.127.4

package/dist/bundled-plugins/awa-bundled/skills/ground-state/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ground-state
-description: "Before starting any non-trivial implementation, dispatch a parallel pre-flight reconnaissance wave to triangulate git state, project infrastructure, and prior-session memory. Wave 4 auto-assembles a verified grounding preamble — a session-scoped artifact the orchestrator pastes verbatim into every subsequent sub-agent brief — eliminating stale-worktree reads and silent wrong-path errors before the first edit."
+description: "Before starting any non-trivial implementation, run a pre-flight reconnaissance pass to triangulate git state, project infrastructure, and prior-session memory. Auto-assembles a verified grounding preamble — a session-scoped artifact the orchestrator pastes verbatim into every subsequent sub-agent brief — eliminating stale-worktree reads and silent wrong-path errors before the first edit."
 read-only: true
 context: fork
 failure_modes:
@@ -12,42 +12,59 @@ failure_modes:
 ## 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`, `memory_search`, and read-only bash (`git status`, `git log`, `git diff`, `cat`, `ls`, `find`, etc.). `memory_search` is non-mutating and is the **only** way to reach the cross-session fact archive — it is in scope for this skill, do not strip it from this list.
+**Constraint: read-only reconnaissance.** You 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`, `memory_search`, and read-only bash (`git status`, `git log`, `git diff`, `cat`, `ls`, `find`, etc.). `memory_search` is non-mutating and is the **only** way to reach the cross-session fact archive — it is in scope for this skill, do not strip it from this list.
 
 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:
+## Inline reconnaissance
 
-**State surveyor** *(domain-aware)*
+Run the three surveys below **directly using your own tools**. Do NOT dispatch any sub-agents via the `agent` or `skill` tools — every lookup in this phase is a deterministic read that you execute yourself using `bash`, `glob`, `read_file`, `grep`, `list_directory`, and `memory_search`. Issue all three surveys in a single batched tool-use round where possible.
 
-| Domain | What to survey |
-|--------|---------------|
-| `software` | Current branch, `git log --oneline -5`, `git status -s`, diff-summary vs `origin/<default-branch>`, stash list. Flag: diverged, uncommitted changes, stale upstream. |
-| `research` | Bibliography state (how many papers collected, citation manager in use), data pipeline status (raw data present? processed?), draft status (outline? partial draft? submitted?), publication target and deadline if known. |
-| `design` | Design system state (component library version, Figma project structure), brand guidelines version, current design phase (research? wireframes? high-fidelity? handoff?), recent design changes. |
-| `business` | Financial data freshness (last updated dates on models/reports), market data recency, stakeholder map (who's involved, who decides), current phase (research? proposal? execution?). |
-| *(other)* | Scan for version-controlled artifacts, recent changes, current project phase, and any state that could cause conflicts. |
+### State survey *(bash)*
 
-**Infrastructure surveyor** *(domain-aware)*
+Issue these commands (combine into one or two bash calls):
+- `git symbolic-ref --short HEAD` — current branch
+- `git rev-parse HEAD` — HEAD SHA
+- `git status -s` — uncommitted changes
+- `git log --oneline -5` — recent commit history
+- `git stash list` — stash state
+- `git rev-list --left-right --count HEAD...@{upstream} 2>/dev/null` — upstream divergence
+
+Adapt what you surface to the domain:
+
+| Domain | What to flag |
+|--------|-------------|
+| `software` | Branch, recent commits, uncommitted changes, stash, upstream divergence. Flag: diverged, uncommitted, stale. |
+| `research` | Version-controlled artifact state, current phase, publication target/deadline if discoverable. |
+| `design` | Design system version, component library state, current phase, recent file changes. |
+| `business` | Financial model freshness, market data recency, current project phase. |
+| *(other)* | Recent changes, current project phase, any state that could cause conflicts. |
+
+When domain is unspecified, infer from working directory contents.
+
+### Infrastructure survey *(bash/glob/read_file)*
+
+Check for relevant tooling and configs. Use the domain table below to decide which paths to probe, then probe them yourself. Return a **5-bullet inventory**.
 
 | Domain | What to scan |
 |--------|-------------|
-| `software` | CI configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`), package scripts (`package.json`, `Makefile`, `pyproject.toml`), existing linters/formatters, authoritative config file locations relevant to the task. Return 5-bullet inventory. |
-| `research` | Reference manager (Zotero, Mendeley, .bib files), LaTeX setup (template, build system), data analysis tools (Jupyter, R, Python scripts), collaboration tools (Overleaf, shared drives), submission system requirements. Return 5-bullet inventory. |
-| `design` | Design tools (Figma, Sketch, Adobe), prototyping tools (Framer, Principle), handoff tools (Zeplin, Storybook), asset pipeline (export scripts, optimization), accessibility testing tools. Return 5-bullet inventory. |
-| `business` | Modeling tools (Excel, Google Sheets, financial software), presentation tools (PowerPoint, Google Slides, Pitch), data sources (CRM, analytics platforms), collaboration tools (Notion, Confluence), approval workflows. Return 5-bullet inventory. |
-| *(other)* | Scan for tooling, build/export pipelines, collaboration infrastructure, and config files relevant to the stated domain. Return 5-bullet inventory. |
+| `software` | CI configs (`ls .github/workflows/ 2>/dev/null`), package scripts (`package.json`, `Makefile`, `pyproject.toml`), linters/formatters, authoritative config files for the task. |
+| `research` | Reference manager (.bib files), LaTeX setup, data analysis tools (Jupyter, R scripts), collaboration setup. |
+| `design` | Design tool configs, prototyping tools, handoff configs (Storybook), asset pipeline scripts. |
+| `business` | Modeling tool configs, presentation formats, data source configs, collaboration tool structure. |
+| *(other)* | Tooling, build/export pipelines, collaboration infrastructure, config files relevant to the stated domain. |
 
-When domain is unspecified, infer from the working directory contents.
+### Memory survey *(memory_search + read_file)*
 
-**Memory surveyor**
 Call the **`memory_search` tool** with keywords from the user's current request — FTS5 syntax, so `term1 AND term2`, `"exact phrase"`, and `prefix*` all work. Run 2–3 query variants (different keyword angles) before concluding nothing is there; a single miss is not evidence of absence. Then read hot memory at `~/.afk/state/memory/HOT.md` and the project overlay — `AFK.md`, or `CLAUDE.md` on a Claude Code surface — for conventions bearing on this task.
 
-**Invariant: the cross-session memory archive is only reachable via the `memory_search` tool.** The backing store is SQLite (`~/.afk/state/memory/memory.db`) and is not greppable. Do not glob or grep any filesystem path looking for memory — `memory_search` is the only route in. Restoring a path-based lookup here silently zeroes this third of the recon wave.
+**Invariant: the cross-session memory archive is only reachable via the `memory_search` tool.** The backing store is SQLite (`~/.afk/state/memory/memory.db`) and is not greppable. Do not glob or grep any filesystem path looking for memory — `memory_search` is the only route in.
+
+Return: relevant facts with 1-line summaries, **plus the stores actually consulted** — e.g. `memory_search: 3 queries, 0 hits; HOT.md: read; AFK.md: read` — so the orchestrator can tell "no relevant memory exists" from "the fork never looked." If `memory_search` is unavailable on this surface, say so explicitly.
 
-Return: relevant facts with 1-line summaries, **plus the stores actually consulted** — e.g. `memory_search: 3 queries, 0 hits; HOT.md: read; AFK.md: read` — so the orchestrator can tell "no relevant memory exists" from "the surveyor never looked." If `memory_search` is unavailable on this surface, say so explicitly instead of returning a bare "no relevant memory found."
+## Synthesis
 
-**Synthesize** into a 6-line ground-truth snapshot:
+Assemble the survey results 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
@@ -57,14 +74,14 @@ Return: relevant facts with 1-line summaries, **plus the stores actually consult
 
 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)
+## 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.
+After the 6-line snapshot is assembled, 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)`.
+1. From your state survey 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 your infrastructure survey output, extract the 2–4 canonical file paths most relevant to the task. 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:
 
 ```
@@ -81,8 +98,8 @@ After the 6-line snapshot is assembled, run a fourth step inline (no additional
 
 **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.
+- 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.
+- 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>` — and halt the wave.
 - 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:**