agent: trim the shared agent flag surface (~24 -> ~10): delete redundant, consolidate tailnet, hide dev/pinning group #362

New issue

Closed

opened 2026-06-26 01:47:22 +00:00 by coilysiren · 2 comments

coilysiren commented

2026-06-26 01:47:22 +00:00

Owner

Goal

Cut warded engineer's flag surface from ~24 to ~10 visible, by deleting redundant/experimental flags, consolidating the tailnet pair, and hiding the dev/pinning group (kept functional, just out of the default --help). Apply in the shared flag helpers so every role (engineer, director per ward#355, advisor) gets the lean surface, not just engineer.

This is the second trim pass; ward#356 already removes the six interactive-cluster flags (--watch, --new-tab, --queue-dir, --launch-name, --channel, --surface). Land this after ward#356 and the in-flight ward#355, all of which touch cmd/ward/agent.go flag helpers.

Delete (remove from the surface)

--instructions / -i - redundant with the positional freeform arg ('<freeform instructions>' already files-then-carries). Keep --instructions-file as the long-body escape hatch.
--with-repo - drop the legacy alias; keep --repo.
--go-bootstrap - experimental (ward#181); remove it from the role surface. (Whether to also tear out the underlying Go-bootstrap path is a separate ward#181 call; this just removes the user-facing flag.)

Compress (consolidate)

--host-net + --ts-sidecar -> one --tailnet flag that auto-picks the mechanism per platform (host-network on a Linux host that is a tailnet node; the standing SOCKS5 sidecar on Docker Desktop where host-net can't reach the tailnet), and implies --aws as both do today. Keep an optional hidden --tailnet-mode=auto|host-net|sidecar escape hatch if a forced pick is ever needed; the visible surface is just --tailnet.

Hide (advanced category - still functional, dropped from default `--help`)

Mark Hidden/advanced so power users + env vars keep working but the default help stays lean:

--image, --ward-version - env-backed (WARD_AGENT_IMAGE, WARD_AGENT_VERSION).
--tag - env-backed (WARD_AGENT_TAG); per-run pinning still works, just hidden.
--ward-source - dev-only (build ward from a local checkout).
--branch - the issue-<N> default is already intelligent.
--no-pull - micro-optimization; the pull is cached.

Keep (the lean visible core)

<owner/repo#N | #N | url | '<freeform>'>, --driver, --repo, --details, --aws, --tailnet, --print, --force, --no-preflight, --instructions-file.

Where

The shared flag builders in cmd/ward/agent.go (agentSurfaceFlags, agentTabFlags already removed by ward#356) and the scratch set (agentScratchFlags, agent_architect.go). Trimming/hiding here cleans every role's surface. Confirm director (ward#355) and advisor pick up the lean set too.

Acceptance

warded engineer --help shows the ~10 visible core flags above and nothing else; the deleted flags error as unknown; the hidden flags still function (and via their env vars).
--host-net/--ts-sidecar are replaced by --tailnet (auto-picks the mechanism, implies --aws); existing tailnet reach is preserved on both Linux and Docker Desktop.
Freeform still works via the positional arg; --instructions-file still handles long bodies.
The lean/hidden surface is shared - director and advisor show the same trimmed help.
docs/agent-engineer.md + the generated roster reflect the trimmed surface; make build, make test, make vet, make lint green.

References

ward#356 (removes the interactive cluster - this builds on it), ward#355 (director's shared flag set this also trims), ward#330/#349 (the host-net + ts-sidecar mechanisms being consolidated into --tailnet), ward#181 (the --go-bootstrap experiment being dropped from the surface), ward#230/#280 (the --repo grant whose --with-repo alias is dropped), cmd/ward/agent.go (agentSurfaceFlags, the shared helpers).

## Goal Cut `warded engineer`'s flag surface from ~24 to ~10 visible, by deleting redundant/experimental flags, consolidating the tailnet pair, and hiding the dev/pinning group (kept functional, just out of the default `--help`). Apply in the **shared** flag helpers so every role (engineer, director per ward#355, advisor) gets the lean surface, not just engineer. This is the second trim pass; ward#356 already removes the six interactive-cluster flags (`--watch`, `--new-tab`, `--queue-dir`, `--launch-name`, `--channel`, `--surface`). Land this **after** ward#356 and the in-flight ward#355, all of which touch `cmd/ward/agent.go` flag helpers. ## Delete (remove from the surface) - **`--instructions` / `-i`** - redundant with the positional freeform arg (`'<freeform instructions>'` already files-then-carries). Keep `--instructions-file` as the long-body escape hatch. - **`--with-repo`** - drop the legacy alias; keep `--repo`. - **`--go-bootstrap`** - experimental (ward#181); remove it from the role surface. (Whether to also tear out the underlying Go-bootstrap path is a separate ward#181 call; this just removes the user-facing flag.) ## Compress (consolidate) - **`--host-net` + `--ts-sidecar` -> one `--tailnet`** flag that **auto-picks the mechanism per platform** (host-network on a Linux host that is a tailnet node; the standing SOCKS5 sidecar on Docker Desktop where host-net can't reach the tailnet), and implies `--aws` as both do today. Keep an optional hidden `--tailnet-mode=auto|host-net|sidecar` escape hatch if a forced pick is ever needed; the visible surface is just `--tailnet`. ## Hide (advanced category - still functional, dropped from default `--help`) Mark `Hidden`/advanced so power users + env vars keep working but the default help stays lean: - **`--image`**, **`--ward-version`** - env-backed (`WARD_AGENT_IMAGE`, `WARD_AGENT_VERSION`). - **`--tag`** - env-backed (`WARD_AGENT_TAG`); per-run pinning still works, just hidden. - **`--ward-source`** - dev-only (build ward from a local checkout). - **`--branch`** - the `issue-<N>` default is already intelligent. - **`--no-pull`** - micro-optimization; the pull is cached. ## Keep (the lean visible core) `<owner/repo#N | #N | url | '<freeform>'>`, `--driver`, `--repo`, `--details`, `--aws`, `--tailnet`, `--print`, `--force`, `--no-preflight`, `--instructions-file`. ## Where The shared flag builders in `cmd/ward/agent.go` (`agentSurfaceFlags`, `agentTabFlags` already removed by ward#356) and the scratch set (`agentScratchFlags`, `agent_architect.go`). Trimming/hiding here cleans **every** role's surface. Confirm director (ward#355) and advisor pick up the lean set too. ## Acceptance - `warded engineer --help` shows the ~10 visible core flags above and nothing else; the deleted flags error as unknown; the hidden flags still function (and via their env vars). - `--host-net`/`--ts-sidecar` are replaced by `--tailnet` (auto-picks the mechanism, implies `--aws`); existing tailnet reach is preserved on both Linux and Docker Desktop. - Freeform still works via the positional arg; `--instructions-file` still handles long bodies. - The lean/hidden surface is shared - director and advisor show the same trimmed help. - `docs/agent-engineer.md` + the generated roster reflect the trimmed surface; `make build`, `make test`, `make vet`, `make lint` green. ## References ward#356 (removes the interactive cluster - this builds on it), ward#355 (director's shared flag set this also trims), ward#330/#349 (the host-net + ts-sidecar mechanisms being consolidated into `--tailnet`), ward#181 (the `--go-bootstrap` experiment being dropped from the surface), ward#230/#280 (the `--repo` grant whose `--with-repo` alias is dropped), `cmd/ward/agent.go` (`agentSurfaceFlags`, the shared helpers).

coilysiren referenced this issue

2026-06-26 07:03:59 +00:00

agent: collapse architect into director's surface phase - roster -> engineer/director/advisor (ward#350 slice 2) #353

coilyco-ops commented

2026-07-01 03:49:31 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-362 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-01T03:49:27Z). 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-362` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-01T03:49:27Z). 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-01 04:21:41 +00:00

feat(agent): trim the shared agent flag surface ~24 -> ~10 (closes #362)

coilysiren closed this issue

2026-07-01 04:21:41 +00:00

coilysiren commented

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

Author

Owner

WARD-OUTCOME: done - consolidated the tailnet flags into --tailnet, deleted --instructions/--with-repo/--go-bootstrap, hid the dev/pinning group; engineer/director/advisor now show ~10 visible flags. Landed on main as c3166ef.

Retrospective:

The code change itself was the easy part. The real work was mapping the blast radius before touching anything: --with-repo turned out to be a shared StringSlice lookup key that three roles read through one buildUpPlan, where --repo means different things (StringSlice grant on engineer, StringFlag scope on director, StringFlag context on advisor). If I had just deleted the alias and switched the reader to "repo", advisor/director would have silently panicked on a type mismatch. The fix was a small extraRepoGrant helper that unions both names, safe because urfave/cli`s StringSlice is nil-tolerant on a non-slice flag. That was the one spot that genuinely fought back.

The tailnet consolidation was satisfying: --host-net/--ts-sidecar collapse into --tailnet with a platform auto-select, and it flows cleanly through the director dispatch and the TCP broker allowlist by forwarding --tailnet --tailnet-mode X. I kept the underlying mechanism docs intact since the routes did not change, only the flag naming.

What surprised me: the catalog pre-commit suite, not the compiler, was the strictest reviewer. The 4000-char / 80-line doc caps and the 2-line / 90-char comment-block rule meant every doc I touched (all deliberately parked just under cap) needed net-neutral trimming, and my verbose helper comments all had to shrink. Good discipline, but it took a few rounds of char-counting.

Confidence is high. Verified against the built binary: help shows exactly the retained core, deleted flags error with "not defined", hidden flags still parse, and the change propagates to all three roles. Full test suite green, and I merged a 4-commit main advance (which reworked the same broker file) with no semantic conflict. No follow-ups worth filing - the GoBootstrap plumbing is now dormant but inert, which I left alone to keep this scoped to the flag surface.

WARD-OUTCOME: done - consolidated the tailnet flags into `--tailnet`, deleted `--instructions`/`--with-repo`/`--go-bootstrap`, hid the dev/pinning group; engineer/director/advisor now show ~10 visible flags. Landed on main as c3166ef. Retrospective: The code change itself was the easy part. The real work was mapping the blast radius before touching anything: `--with-repo` turned out to be a shared StringSlice lookup key that three roles read through one `buildUpPlan`, where `--repo` means different things (StringSlice grant on engineer, StringFlag scope on director, StringFlag context on advisor). If I had just deleted the alias and switched the reader to `"repo"`, advisor/director would have silently panicked on a type mismatch. The fix was a small `extraRepoGrant` helper that unions both names, safe because urfave/cli`s StringSlice is nil-tolerant on a non-slice flag. That was the one spot that genuinely fought back. The tailnet consolidation was satisfying: `--host-net`/`--ts-sidecar` collapse into `--tailnet` with a platform auto-select, and it flows cleanly through the director dispatch and the TCP broker allowlist by forwarding `--tailnet --tailnet-mode X`. I kept the underlying mechanism docs intact since the routes did not change, only the flag naming. What surprised me: the catalog pre-commit suite, not the compiler, was the strictest reviewer. The 4000-char / 80-line doc caps and the 2-line / 90-char comment-block rule meant every doc I touched (all deliberately parked just under cap) needed net-neutral trimming, and my verbose helper comments all had to shrink. Good discipline, but it took a few rounds of char-counting. Confidence is high. Verified against the built binary: help shows exactly the retained core, deleted flags error with "not defined", hidden flags still parse, and the change propagates to all three roles. Full test suite green, and I merged a 4-commit main advance (which reworked the same broker file) with no semantic conflict. No follow-ups worth filing - the `GoBootstrap` plumbing is now dormant but inert, which I left alone to keep this scoped to the flag surface.

coilysiren added the

headless

labels

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