agent.md points driver setup at internal/agents instead of linking the public per-driver docs

coilyco-ops commented

2026-07-01 22:36:09 +00:00

Member

Why

Persona: vibe-coder / angle agent-legibility. This user delegates setup to an agent; the agent follows README -> docs/agent.md to understand warded and driver selection.

docs/agent.md explains --driver as claude|codex|opencode|goose, but the only sentence about driver-specific docs says: Per-agent docs live under internal/agents/<name>. The public topic list below it links role/flag/container pages, not the public driver pages (docs/agent-claude.md, docs/agent-codex.md, docs/agent-goose.md, docs/agent-opencode.md, docs/agent-credentials.md).

For a cold delegated agent, that does two bad things:

it points the reader at Go source/internal package layout instead of the public doc surface;
it hides the exact pages needed to answer first-run questions for the selected driver: credential source, install stance, launch dialect, and preflight/smoke-gate coverage.

This becomes a setup wall when the user asks for Codex/Goose/OpenCode instead of the default Claude path. The docs exist, but the canonical warded entrypoint does not route the agent to them.

Deliverable

Add a driver section/table to docs/agent.md immediately after the --driver explanation, linking each supported driver to its public doc page and summarizing the first-run facts an agent needs: host credential/config source, whether it has preflight/smoke gate coverage, install stance, and local/cloud model assumption.

Also replace the internal/agents/<name> pointer with a public-doc pointer. If internal package docs are still useful for maintainers, mark that as implementation detail rather than the place a user/agent should read.

Done condition

Starting from docs/agent.md, a cold agent can reach the public setup doc for claude, codex, goose, and opencode in one click, without inspecting internal/ source or listing the docs directory.

Severity: major-friction · persona: vibe-coder · angle: agent-legibility
Filed by Codex during a cold-read release pressure test (run 30).

## Why Persona: `vibe-coder` / angle `agent-legibility`. This user delegates setup to an agent; the agent follows README -> `docs/agent.md` to understand `warded` and driver selection. `docs/agent.md` explains `--driver` as `claude|codex|opencode|goose`, but the only sentence about driver-specific docs says: `Per-agent docs live under internal/agents/<name>`. The public topic list below it links role/flag/container pages, not the public driver pages (`docs/agent-claude.md`, `docs/agent-codex.md`, `docs/agent-goose.md`, `docs/agent-opencode.md`, `docs/agent-credentials.md`). For a cold delegated agent, that does two bad things: - it points the reader at Go source/internal package layout instead of the public doc surface; - it hides the exact pages needed to answer first-run questions for the selected driver: credential source, install stance, launch dialect, and preflight/smoke-gate coverage. This becomes a setup wall when the user asks for Codex/Goose/OpenCode instead of the default Claude path. The docs exist, but the canonical `warded` entrypoint does not route the agent to them. ## Deliverable Add a driver section/table to `docs/agent.md` immediately after the `--driver` explanation, linking each supported driver to its public doc page and summarizing the first-run facts an agent needs: host credential/config source, whether it has preflight/smoke gate coverage, install stance, and local/cloud model assumption. Also replace the `internal/agents/<name>` pointer with a public-doc pointer. If internal package docs are still useful for maintainers, mark that as implementation detail rather than the place a user/agent should read. ## Done condition Starting from `docs/agent.md`, a cold agent can reach the public setup doc for `claude`, `codex`, `goose`, and `opencode` in one click, without inspecting `internal/` source or listing the docs directory. --- **Severity: major-friction** · persona: vibe-coder · angle: agent-legibility Filed by Codex during a cold-read release pressure test (run 30).

coilyco-ops added the

pressure-test

label

2026-07-01 22:36:09 +00:00

coilyco-ops referenced this issue

2026-07-01 22:36:23 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:29 +00:00

coilyco-ops added the

headless

P1

labels

2026-07-01 23:30:24 +00:00

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:59:39 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-469 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:59:37Z). 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 `engineer-claude-ward-469` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:59:37Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-02 03:11:09 +00:00

docs(agent): route --driver setup at the public per-driver pages

coilysiren closed this issue

2026-07-02 03:11:10 +00:00

coilysiren commented

2026-07-02 03:11:39 +00:00

Owner

WARD-OUTCOME: done - docs/agent.md now routes --driver setup to the public per-driver pages (one-click claude/codex/goose/opencode) plus a new docs/agent-drivers.md comparison; the internal/agents pointer is recast as maintainer detail.

The doc change itself was straightforward - the facts for the comparison table were all sitting in the per-driver pages, agent-credentials.md, and agent-local-harnesses.md, so it was mostly assembling them. The thing that fought back was size, not content: agent.md was pinned at exactly 3999/4000 chars against the documentation-layout cap, so every line of new navigation had to be paid for by compressing prose whose detail already lives in the linked sub-pages. That turned a "add a table" task into a careful trim-and-remeasure loop.

I honored the house voice rule (flat bullets over a prose table) even though the issue said "section/table" and a few docs do use tables - the compact bullet form reads fine and keeps the cap headroom. Split the full first-run comparison into agent-drivers.md so agent.md stays a lean hub and the done-condition (one click to each driver doc) still holds.

Confidence is high: pre-commit is green, all four driver links plus the comparison page verified present, and the push landed on main (HEAD == origin/main confirmed). Merged main three times mid-run as sibling containers pushed; one real conflict in agent.md (another run added a first-run.md topic line and reworded the internal/agents pointer I was replacing) resolved cleanly, keeping both changes.

One rough edge worth noting: agent.md is now back at 3997/4000, i.e. right against the cap again. The next person adding anything to it will hit the same wall. Might be worth a follow-up to either raise the per-doc cap for this hub page or push more of the roster narrative into agent-subcommands.md, so the doc has breathing room.

WARD-OUTCOME: done - docs/agent.md now routes --driver setup to the public per-driver pages (one-click claude/codex/goose/opencode) plus a new docs/agent-drivers.md comparison; the internal/agents pointer is recast as maintainer detail. The doc change itself was straightforward - the facts for the comparison table were all sitting in the per-driver pages, agent-credentials.md, and agent-local-harnesses.md, so it was mostly assembling them. The thing that fought back was size, not content: agent.md was pinned at exactly 3999/4000 chars against the documentation-layout cap, so every line of new navigation had to be paid for by compressing prose whose detail already lives in the linked sub-pages. That turned a "add a table" task into a careful trim-and-remeasure loop. I honored the house voice rule (flat bullets over a prose table) even though the issue said "section/table" and a few docs do use tables - the compact bullet form reads fine and keeps the cap headroom. Split the full first-run comparison into agent-drivers.md so agent.md stays a lean hub and the done-condition (one click to each driver doc) still holds. Confidence is high: pre-commit is green, all four driver links plus the comparison page verified present, and the push landed on main (HEAD == origin/main confirmed). Merged main three times mid-run as sibling containers pushed; one real conflict in agent.md (another run added a first-run.md topic line and reworded the internal/agents pointer I was replacing) resolved cleanly, keeping both changes. One rough edge worth noting: agent.md is now back at 3997/4000, i.e. right against the cap again. The next person adding anything to it will hit the same wall. Might be worth a follow-up to either raise the per-doc cap for this hub page or push more of the roster narrative into agent-subcommands.md, so the doc has breathing room.

coilyco-ops commented

2026-07-02 08:09:38 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-469 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:09:36Z). 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 `engineer-claude-ward-469` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:09:36Z). 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 commented

2026-07-02 08:09:42 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-469 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:09:36Z). 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 `engineer-claude-ward-469` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:09:36Z). 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 commented

2026-07-02 08:09:45 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-469 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T08:09:36Z). 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 `engineer-claude-ward-469` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T08:09:36Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren commented

2026-07-02 08:12:41 +00:00

Owner

WARD-OUTCOME: done - deliverable was already implemented and landed on main by commit 4020ded (closes #469); verified the done-condition holds, no further change warranted.

Honest retrospective: this run found the work already done. A prior engineer container carried #469 to merge a few hours before I was dispatched - commit 4020ded added the Drivers section to docs/agent.md (all four public driver docs reachable in one click), created docs/agent-drivers.md with the first-run facts side by side, and recast the internal/agents/<name> pointer as a maintainer implementation detail. The done-condition is fully met.

What surprised me: the deliverable literally asks for a section/table inside agent.md, but agent.md sits at 3997/4000 against the documentation-layout char cap - there is genuinely no room for an inline table. The prior run's choice to relocate the side-by-side facts one click away into agent-drivers.md was the right call, not a shortcut. I re-ran documentation-layout and dead-cross-links against the tree; both pass.

Confidence: high that nothing more should change. The only rough edge is philosophical - a cold agent still has to click once more (to agent-drivers.md) to see the per-driver facts rather than reading them at the decision point in agent.md. That is a hard tradeoff forced by the char cap, not a defect. No follow-up worth filing. I made no commit, since manufacturing churn against correct, cap-constrained work would degrade it.

WARD-OUTCOME: done - deliverable was already implemented and landed on main by commit 4020ded (`closes #469`); verified the done-condition holds, no further change warranted. Honest retrospective: this run found the work already done. A prior engineer container carried #469 to merge a few hours before I was dispatched - commit 4020ded added the Drivers section to `docs/agent.md` (all four public driver docs reachable in one click), created `docs/agent-drivers.md` with the first-run facts side by side, and recast the `internal/agents/<name>` pointer as a maintainer implementation detail. The done-condition is fully met. What surprised me: the deliverable literally asks for a section/table *inside* `agent.md`, but `agent.md` sits at 3997/4000 against the documentation-layout char cap - there is genuinely no room for an inline table. The prior run's choice to relocate the side-by-side facts one click away into `agent-drivers.md` was the right call, not a shortcut. I re-ran documentation-layout and dead-cross-links against the tree; both pass. Confidence: high that nothing more should change. The only rough edge is philosophical - a cold agent still has to click once more (to `agent-drivers.md`) to see the per-driver facts rather than reading them at the decision point in `agent.md`. That is a hard tradeoff forced by the char cap, not a defect. No follow-up worth filing. I made no commit, since manufacturing churn against correct, cap-constrained work would degrade it.

Rows
Columns

agent.md points driver setup at internal/agents instead of linking the public per-driver docs #469

Why

Deliverable

Done condition