README still advertises retired `warded engineer --watch` even though the flag now errors

coilyco-ops commented

2026-07-01 22:35:29 +00:00

Owner

Why

Persona: vibe-coder / angle agent-legibility. This user will paste the repo URL into an agent and ask it to set ward up, so the first copy-pasteable command in the README matters more than the deeper command reference.

Cold trail: README -> docs/agent.md -> docs/agent-flags.md.

README's opening section still says: warded engineer #98 --watch attaches to watch. But docs/agent-flags.md says --watch and --new-tab are retired, engineer is detached/autonomous only, and those flags now error as unknown. A delegated setup agent following the README can therefore pick the only visible attached-run example, execute it, and hit a CLI error before learning that interactive work moved to director.

This is not just stale prose: it is a first-screen command contradiction between the public front page and the agent command docs.

Deliverable

Update the README's warded paragraph so it does not advertise --watch. Replace it with a currently valid detached example and, if an attached/interactive path should be discoverable from the front page, point to the director surface explicitly.

Done condition

Every warded command shown in the README succeeds against the current CLI, or is clearly marked as historical/retired and not presented as a command to run.

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 will paste the repo URL into an agent and ask it to set ward up, so the first copy-pasteable command in the README matters more than the deeper command reference. Cold trail: README -> `docs/agent.md` -> `docs/agent-flags.md`. README's opening section still says: `warded engineer #98 --watch` attaches to watch. But `docs/agent-flags.md` says `--watch` and `--new-tab` are retired, engineer is detached/autonomous only, and those flags now error as unknown. A delegated setup agent following the README can therefore pick the only visible attached-run example, execute it, and hit a CLI error before learning that interactive work moved to `director`. This is not just stale prose: it is a first-screen command contradiction between the public front page and the agent command docs. ## Deliverable Update the README's `warded` paragraph so it does not advertise `--watch`. Replace it with a currently valid detached example and, if an attached/interactive path should be discoverable from the front page, point to the `director` surface explicitly. ## Done condition Every `warded` command shown in the README succeeds against the current CLI, or is clearly marked as historical/retired and not presented as a command to run. --- **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:35:29 +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 commented

2026-07-01 22:43:17 +00:00

Author

Owner

+1 — independently hit via agent-power-user/feature-gaps, run 30; near-dup #474 filed in the same concurrency window (both quote agent-flags.md ward#356). Fold whichever.

coilyco-ops referenced this issue

2026-07-01 22:43:18 +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:30 +00:00

coilyco-ops added the

labels

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

coilyco-ops referenced this issue

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

README instructs warded engineer #98 --watch, a flag retired in ward#356 that now errors as unknown #474

coilyco-ops commented

2026-07-01 23:58:18 +00:00

Author

Owner

Canonical for #474 (merged). The --watch fix lands inside the #444 README epic; closes with that PR. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops referenced this issue

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

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

coilysiren commented

2026-07-02 02:48:14 +00:00

Owner

Verification close from the ward#492 burndown director: the #444 epic commit b0ce6d5 dropped the retired engineer --watch example from the README opening, and a grep of main finds no live --watch example anywhere - the only remaining mentions are docs/agent-flags.md's 'Retired' section, which correctly documents the retirement (ward#356). The delegated-setup agent this ticket protects can no longer copy a dead flag from the README. Closing via the issue API. Recorded by Claude Code (Fable) during the ward#492 burndown session.

Verification close from the ward#492 burndown director: the #444 epic commit `b0ce6d5` dropped the retired `engineer --watch` example from the README opening, and a grep of main finds no live `--watch` example anywhere - the only remaining mentions are docs/agent-flags.md's 'Retired' section, which correctly documents the retirement (ward#356). The delegated-setup agent this ticket protects can no longer copy a dead flag from the README. Closing via the issue API. Recorded by Claude Code (Fable) during the ward#492 burndown session.

coilysiren closed this issue

2026-07-02 02:48:14 +00:00

coilysiren referenced this issue

2026-07-02 07:10:55 +00:00

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

coilyco-ops commented

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

Author

Owner

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

Author

Owner

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

Author

Owner

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

docs(readme): retire the last --watch cue, point interactive work at director

coilysiren commented

2026-07-02 08:15:00 +00:00

Owner

WARD-OUTCOME: done - README now points the retired --watch attach path explicitly at the director surface; every warded command shown is valid.

Retrospective: the literal --watch example was already gone (dropped by the #444 epic, commit b0ce6d5), and this ticket had even been API-closed once from the ward#492 burndown. So the surprising part was discovering the first half of the deliverable was done before I touched anything - the honest move was not to re-close and walk away, but to land the deliverable's conditional second half: a front-page reader who remembers an attach flag now gets told, on the README, that interactive work moved to director. That's the gap the burndown close left open.

The only thing that fought back was the doc-size cap - README sits right at the 130-line / 13450-char budget, so a two-sentence paragraph blew it three times. I folded the pointer into one line and trimmed the redundant first-run/FEATURES tail (both still linked in 'Where to go next') to net under budget. Confident in the result: all hooks green, all four warded commands verified against the current CLI (director --org is a real flag, --watch is in the rejected set per agent_director_test.go), pushed clean to main. No follow-ups worth filing - #444/#474 already fold the sibling passes.

WARD-OUTCOME: done - README now points the retired `--watch` attach path explicitly at the `director` surface; every `warded` command shown is valid. Retrospective: the literal `--watch` example was already gone (dropped by the #444 epic, commit b0ce6d5), and this ticket had even been API-closed once from the ward#492 burndown. So the surprising part was discovering the *first* half of the deliverable was done before I touched anything - the honest move was not to re-close and walk away, but to land the deliverable's conditional second half: a front-page reader who remembers an attach flag now gets told, on the README, that interactive work moved to director. That's the gap the burndown close left open. The only thing that fought back was the doc-size cap - README sits right at the 130-line / 13450-char budget, so a two-sentence paragraph blew it three times. I folded the pointer into one line and trimmed the redundant first-run/FEATURES tail (both still linked in 'Where to go next') to net under budget. Confident in the result: all hooks green, all four `warded` commands verified against the current CLI (`director --org` is a real flag, `--watch` is in the rejected set per agent_director_test.go), pushed clean to main. No follow-ups worth filing - #444/#474 already fold the sibling passes.

Rows
Columns

README still advertises retired warded engineer --watch even though the flag now errors #468

Why

Deliverable

Done condition

README still advertises retired `warded engineer --watch` even though the flag now errors #468