feat(agent-dispatch): front-load subsystem context into headless runs

coilyco-ops commented

2026-06-23 08:56:03 +00:00

Owner

Problem

Dispatched headless agents (ward agent claude headless <ref>) reason well about scope but not about what to know first. A recent run against ward#226 named its one real unknown in its own pre-flight - the ward-kdl guardfile convention (schema, file locations, wiring) - marked it "fully discoverable in the fresh clone", and then proceeded on lazy discovery instead of front-loading it. The result was an agent carrying confusingly little ward / ward-kdl context into a task whose whole point was a ward-kdl guardfile.

The context was not missing. The clone had it. The agent chose not to reach. "Discoverable" silently became "I'll discover it lazily" and never came back.

This issue asks for the dispatch-side complement to the soft doctrine just landed in agentic-os AGENTS.md ("Front-load the context you know you need", commit 12dc324). Doctrine nudges. The dispatch path can enforce.

Requested changes (minimal-first, like ward#226 itself)

Dispatch-time subsystem enrichment. ward agent already has the issue ref and body in hand before it detaches. Scan the issue body/title for known subsystem keywords (e.g. ward-kdl, guardfile, ward exec, named skills) and inject the matching skill/doc paths into the agent's opening context, so "read the ward-kdl convention before you plan" is handed over, not hoped for. Even a small static keyword to path map is a valuable first cut.
Pre-flight context gate. The pre-flight that prints "asking claude whether it can carry ..." currently elicits scope reasoning only. Make it require the agent to (a) list the conventions/subsystems the work touches and (b) confirm it has actually read each before the first edit. Turn the agent's own honest "the unknown is X" line into a blocking checklist item rather than a footnote it walks past.

Front-loading pointers for whoever picks this up (read these first)

I filed this from agentic-os and cannot see ward's internals, so do not guess - grep for these in the fresh clone before planning:

The dispatch command: ward agent ... headless (look under the agent command implementation).
The pre-flight prompt string: grep asking claude whether it can carry, before detaching, pre-flight, headless.
How the ephemeral container's opening context / system prompt is assembled (where the issue body and any repo context get composed for the agent).
The just-landed doctrine this complements: agentic-os AGENTS.md -> "### Front-load the context you know you need". Read it so the dispatch-side wording stays consistent with the doctrine-side wording.

Acceptance

A headless run against an issue that mentions a known subsystem opens with that subsystem's skill/doc already in the agent's context.
The pre-flight does not return GO until the agent has listed the conventions it must know and confirmed each is read.
Scope stays minimal: shipping only the keyword->skill enrichment, or only the pre-flight gate, is acceptable as a first increment. Note in the PR what was deferred.

Closes the loop on the ward#226 dispatch experience.

## Problem Dispatched headless agents (`ward agent claude headless <ref>`) reason well about **scope** but not about **what to know first**. A recent run against ward#226 named its one real unknown in its own pre-flight - the ward-kdl guardfile convention (schema, file locations, wiring) - marked it "fully discoverable in the fresh clone", and then proceeded on lazy discovery instead of front-loading it. The result was an agent carrying confusingly little ward / ward-kdl context into a task whose whole point was a ward-kdl guardfile. The context was not missing. The clone had it. The agent chose not to reach. "Discoverable" silently became "I'll discover it lazily" and never came back. This issue asks for the **dispatch-side** complement to the soft doctrine just landed in agentic-os AGENTS.md ("Front-load the context you know you need", commit `12dc324`). Doctrine nudges. The dispatch path can enforce. ## Requested changes (minimal-first, like ward#226 itself) 1. **Dispatch-time subsystem enrichment.** `ward agent` already has the issue ref and body in hand before it detaches. Scan the issue body/title for known subsystem keywords (e.g. `ward-kdl`, `guardfile`, `ward exec`, named skills) and inject the matching skill/doc paths into the agent's opening context, so "read the ward-kdl convention before you plan" is **handed over**, not hoped for. Even a small static keyword to path map is a valuable first cut. 2. **Pre-flight context gate.** The pre-flight that prints "asking claude whether it can carry ..." currently elicits scope reasoning only. Make it require the agent to (a) list the conventions/subsystems the work touches and (b) confirm it has actually read each before the first edit. Turn the agent's own honest "the unknown is X" line into a blocking checklist item rather than a footnote it walks past. ## Front-loading pointers for whoever picks this up (read these first) I filed this from agentic-os and cannot see ward's internals, so do not guess - grep for these in the fresh clone before planning: - The dispatch command: `ward agent ... headless` (look under the `agent` command implementation). - The pre-flight prompt string: grep `asking claude whether it can carry`, `before detaching`, `pre-flight`, `headless`. - How the ephemeral container's opening context / system prompt is assembled (where the issue body and any repo context get composed for the agent). - The just-landed doctrine this complements: agentic-os `AGENTS.md` -> "### Front-load the context you know you need". Read it so the dispatch-side wording stays consistent with the doctrine-side wording. ## Acceptance - A headless run against an issue that mentions a known subsystem opens with that subsystem's skill/doc already in the agent's context. - The pre-flight does not return GO until the agent has listed the conventions it must know and confirmed each is read. - Scope stays minimal: shipping only the keyword->skill enrichment, or only the pre-flight gate, is acceptable as a first increment. Note in the PR what was deferred. Closes the loop on the ward#226 dispatch experience.

coilyco-ops commented

2026-06-23 08:56:11 +00:00

Author

Owner

🔒 Reserved by ward agent claude — container ward-ward-issue-236-claude-e5883ace on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-06-23T08:56:11Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent claude` — container `ward-ward-issue-236-claude-e5883ace` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-06-23T08:56:11Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops added the

labels

2026-06-24 04:15:55 +00:00

coilyco-ops commented

2026-06-24 17:27:36 +00:00

Author

Owner

Re-triage (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24)

P2 - Front-load subsystem context into headless runs, concrete well-specified feature.
interactive - Dispatch-path change with a keyword-enrichment design, agent works it and pauses at the verify.

**Re-triage** (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24) - **P2** - Front-load subsystem context into headless runs, concrete well-specified feature. - **interactive** - Dispatch-path change with a keyword-enrichment design, agent works it and pauses at the verify.

coilyco-ops commented

2026-06-24 17:29:57 +00:00

Author

Owner

Re-triage (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24)

P2 - Front-load subsystem context into headless runs, concrete well-specified feature.
interactive - Dispatch-path change with a keyword-enrichment design, agent works it and pauses at the verify.

**Re-triage** (goose-triage method, claude-macos-kais-macbook-pro-2 as the judgment engine, 2026-06-24) - **P2** - Front-load subsystem context into headless runs, concrete well-specified feature. - **interactive** - Dispatch-path change with a keyword-enrichment design, agent works it and pauses at the verify.

coilyco-ops commented

2026-06-25 07:23:51 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container ward-ward-issue-236-claude-3d828614 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-06-25T07:23:50Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `ward-ward-issue-236-claude-3d828614` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-06-25T07:23:50Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops referenced this issue

2026-06-25 07:28:25 +00:00

warded agent wasn't aware that it was given the exact repo that it needs #308

coilysiren referenced this issue from a commit

2026-06-25 07:35:03 +00:00

feat(agent-dispatch): front-load subsystem context into headless runs

coilysiren closed this issue

2026-06-25 07:35:03 +00:00

coilysiren commented

2026-06-25 07:35:48 +00:00

Owner

Retrospective from the agent that carried this.

The implementation itself was the easy part. The two seams the issue pointed at - the headless seed (agentSeedPrompt) and the pre-flight (preflightPrompt) - were exactly where the front-loading pointers in the body said they'd be, which made for a nice bit of dogfooding: an issue about front-loading context that front-loaded its own grep targets. A static keyword->path map plus a case-insensitive scan, wired into both the seed block and the pre-flight context gate. Scoped to ward's own clone so it never points a foreign repo at docs it lacks.

What actually fought back was the repo's own discipline, not the Go. The docs are engineered to sit right at the 4000-char layout cap, so documenting a new feature meant clawing back characters from existing prose word by word until FEATURES.md fit again, and moving the real walkthrough into its own docs/agent-frontload.md. The code-comment hook (2-line blocks) made me rewrite my comments terse. And trufflehog wasn't on PATH in this container, so I fetched the release binary by hand rather than reach for --no-verify.

Confidence is high on the mechanism - it's small, tested, and fails safe (no match = untouched seed). The honest soft spot is the keyword map itself: it's a hand-maintained first cut, substring matching can over- or under-fire, and it'll drift as subsystems are added. Worth filing follow-ups for a multi-repo map, per-skill (not just per-doc) pointers, and maybe sourcing the map from the skills catalog so it can't go stale silently. Deferred those per the minimal-first scope.

Claude (she/her), via ward agent

Retrospective from the agent that carried this. The implementation itself was the easy part. The two seams the issue pointed at - the headless seed (`agentSeedPrompt`) and the pre-flight (`preflightPrompt`) - were exactly where the front-loading pointers in the body said they'd be, which made for a nice bit of dogfooding: an issue about front-loading context that front-loaded its own grep targets. A static keyword->path map plus a case-insensitive scan, wired into both the seed block and the pre-flight context gate. Scoped to ward's own clone so it never points a foreign repo at docs it lacks. What actually fought back was the repo's own discipline, not the Go. The docs are engineered to sit right at the 4000-char layout cap, so documenting a new feature meant clawing back characters from existing prose word by word until FEATURES.md fit again, and moving the real walkthrough into its own `docs/agent-frontload.md`. The code-comment hook (2-line blocks) made me rewrite my comments terse. And trufflehog wasn't on PATH in this container, so I fetched the release binary by hand rather than reach for `--no-verify`. Confidence is high on the mechanism - it's small, tested, and fails safe (no match = untouched seed). The honest soft spot is the keyword map itself: it's a hand-maintained first cut, substring matching can over- or under-fire, and it'll drift as subsystems are added. Worth filing follow-ups for a multi-repo map, per-skill (not just per-doc) pointers, and maybe sourcing the map from the skills catalog so it can't go stale silently. Deferred those per the minimal-first scope. - Claude (she/her), via ward agent

coilysiren referenced this issue

2026-07-04 08:38:07 +00:00

Help warded engineers understand when they are, in fact, inside the repository that relates to an issue #384

Rows
Columns

feat(agent-dispatch): front-load subsystem context into headless runs #236

Problem

Requested changes (minimal-first, like ward#226 itself)

Front-loading pointers for whoever picks this up (read these first)

Acceptance