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

New issue

Closed

opened 2026-06-26 00:29:30 +00:00 by coilysiren · 3 comments

coilysiren commented

2026-06-26 00:29:30 +00:00

Owner

Slice 2 of the unified-director design (ward#350). Collapse the standalone architect role into director's interactive-surface phase. Roster shrinks to engineer / director / advisor (3 roles). Builds on ward#351 (the heartbeat + surface spine).

Why

architect and director's surface phase are the same thing - a read-only interactive session that reads the clone + operating context and dispatches siblings through the socket but never pushes its own tree. The unified director already drains-then-surfaces (ward#351); when there is no actionable headless work, it surfaces immediately - which is architect's use case. So a separate architect command is redundant: architect = director with nothing to drain.

Scope

Remove the standalone architect command - cmd/ward/agent_architect.go / agentArchitectCommand and its entry in agentCommand()'s Commands slice. warded architect becomes an unknown command.
runScratchSession is retained, now driven by director's surface phase (architect was its only caller since ward#347). The read-only scratch bring-up is the surface session; wire it there.
Preserve the "just scope now" path - do not lose architect's behavior of "give me a read-only interactive scope+dispatch session right now, not a backlog drain." Resolve how: warded director should surface immediately when there is no actionable headless work (covers a clear backlog), and consider a --surface/--scope flag to skip the drain and go straight to the interactive session for an explicit scoping run. Pick one and note it - the capability must survive, not just the role name.
Roster -> 3. The generated agent-roster (ward#348) + its drift test must reflect engineer/director/advisor; regenerate the roster doc (the drift test reds until you do).
Docs. Fold docs/agent-architect.md into docs/agent-director.md's surface-phase section (then remove it); update docs/agent.md, docs/agent-subcommands.md, the generated roster, and docs/FEATURES.md to three roles.
Tests. Reconcile agent_architect_test.go - the scratch-session behavior it covers now lives under director's surface.

Sequencing note (read before dispatching)

director's surface phase is not yet live-proven (ward#351's retro: the interactive surface is "validated by construction, not a live run"). This change makes director's surface the only interactive session. Strongly prefer a live warded director drain->surface->resume exercise to confirm the surface is solid - either before this lands, or as part of its acceptance. Do not remove the working architect session on top of an unexercised replacement without that check.

Out of scope

Mid-drain steering UX (a separate ward#350 slice).
The reservation-conflict-parks-failed bug (ward#352).

Acceptance

warded architect is gone (errors as an unknown command); the roster is engineer / director / advisor.
The read-only interactive scope+dispatch capability survives: warded director reaches that session (immediately when no headless work is actionable, and/or via the chosen --surface/--scope path), read-only on its own clone, able to dispatch siblings.
The generated roster (ward#348) + drift test reflect three roles; docs/agent-architect.md folded into agent-director.md and removed; docs/agent.md / agent-subcommands.md / FEATURES.md updated.
A live director surface exercise has been run (or is recorded as the gating check) per the sequencing note.
make build, make test, make vet, make lint green.

References

ward#350 (the unified-director design - this is slice 2), ward#351 (slice 1, the surface phase this folds architect into), ward#347 (created architect + the four-role roster), ward#348 (the generated roster + drift test to shrink to three), cmd/ward/agent_architect.go + runScratchSession, docs/agent-architect.md / agent-director.md.

Slice 2 of the unified-director design (ward#350). Collapse the standalone `architect` role into director's interactive-surface phase. Roster shrinks to **engineer / director / advisor** (3 roles). Builds on ward#351 (the heartbeat + surface spine). ## Why architect and director's surface phase are the **same thing** - a read-only interactive session that reads the clone + operating context and dispatches siblings through the socket but never pushes its own tree. The unified director already drains-then-surfaces (ward#351); when there is no actionable headless work, it surfaces immediately - which **is** architect's use case. So a separate `architect` command is redundant: **architect = director with nothing to drain.** ## Scope - **Remove the standalone `architect` command** - `cmd/ward/agent_architect.go` / `agentArchitectCommand` and its entry in `agentCommand()`'s `Commands` slice. `warded architect` becomes an unknown command. - **`runScratchSession` is retained, now driven by director's surface phase** (architect was its only caller since ward#347). The read-only scratch bring-up is the surface session; wire it there. - **Preserve the "just scope now" path** - do not lose architect's behavior of "give me a read-only interactive scope+dispatch session right now, not a backlog drain." Resolve how: `warded director` should surface immediately when there is no actionable headless work (covers a clear backlog), and consider a `--surface`/`--scope` flag to skip the drain and go straight to the interactive session for an explicit scoping run. Pick one and note it - the capability must survive, not just the role name. - **Roster -> 3.** The generated agent-roster (ward#348) + its drift test must reflect engineer/director/advisor; regenerate the roster doc (the drift test reds until you do). - **Docs.** Fold `docs/agent-architect.md` into `docs/agent-director.md`'s surface-phase section (then remove it); update `docs/agent.md`, `docs/agent-subcommands.md`, the generated roster, and `docs/FEATURES.md` to three roles. - **Tests.** Reconcile `agent_architect_test.go` - the scratch-session behavior it covers now lives under director's surface. ## Sequencing note (read before dispatching) director's surface phase is **not yet live-proven** (ward#351's retro: the interactive surface is "validated by construction, not a live run"). This change makes director's surface the **only** interactive session. Strongly prefer a **live `warded director` drain->surface->resume exercise** to confirm the surface is solid - either before this lands, or as part of its acceptance. Do not remove the working architect session on top of an unexercised replacement without that check. ## Out of scope - Mid-drain steering UX (a separate ward#350 slice). - The reservation-conflict-parks-failed bug (ward#352). ## Acceptance - `warded architect` is gone (errors as an unknown command); the roster is engineer / director / advisor. - The read-only interactive scope+dispatch capability **survives**: `warded director` reaches that session (immediately when no headless work is actionable, and/or via the chosen `--surface`/`--scope` path), read-only on its own clone, able to dispatch siblings. - The generated roster (ward#348) + drift test reflect three roles; `docs/agent-architect.md` folded into `agent-director.md` and removed; `docs/agent.md` / `agent-subcommands.md` / `FEATURES.md` updated. - A live director surface exercise has been run (or is recorded as the gating check) per the sequencing note. - `make build`, `make test`, `make vet`, `make lint` green. ## References ward#350 (the unified-director design - this is slice 2), ward#351 (slice 1, the surface phase this folds architect into), ward#347 (created architect + the four-role roster), ward#348 (the generated roster + drift test to shrink to three), `cmd/ward/agent_architect.go` + `runScratchSession`, `docs/agent-architect.md` / `agent-director.md`.

coilysiren referenced this issue

2026-06-26 01:13:01 +00:00

agent: bare 'warded' (no args) should print the agent-type roster, not the CLI flag dump #360

coilysiren referenced this issue

2026-06-26 02:51:23 +00:00

agent: bare 'warded' (no args) should print the agent-type roster, not the CLI flag dump #360

coilysiren commented

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

Author

Owner

Gate lifted: Kai confirmed warded director is functional and running at full speed live (drain->surface proven, closing the #351 "validated by construction, not a live run" gap). This is now dispatchable. Only remaining block is file-overlap with the in-flight #360 (agent.go) and #361 (agent_director.go) - dispatch once those land. It also shares agent.go/roster with #362 (flag trim), so #353 and #362 run sequentially, not parallel.

coilysiren commented

2026-06-26 07:04:30 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container ward-ward-issue-353-claude-3252f02d on host 4f2062d4fed1 is carrying this issue (reserved 2026-06-26T07:04:30Z). 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-353-claude-3252f02d` on host `4f2062d4fed1` is carrying this issue (reserved 2026-06-26T07:04:30Z). 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-06-26 07:43:43 +00:00

feat(agent): collapse architect into director's surface phase (ward#353)

coilysiren closed this issue

2026-06-26 07:43:43 +00:00

coilysiren commented

2026-06-26 07:44:30 +00:00

Author

Owner

Landed. The core was smaller than it looked: architect and the directors drain-surface were already the same runScratchSession bring-up, so collapsing them was mostly deletion — unregister the command, rename the file/verb to directorSurfaceCommand/surface, drop the orphaned roleArchitect, and re-point the read-only context block at the heartbeat instead of "the architect."

What actually fought back was nothing in the Go — it was the doc-size discipline. Nearly every agent doc sits deliberately a few chars under the 4000-char cap, so every cross-reference I added (and the longer agent-director-surface.md filename) tipped 8+ files over at once. I ended up renaming the doc to the shorter agent-surface.md and trimming prose char-by-char to claw back budget. Then two rounds of main integration: ward#370 (--org scope) and ward#374 (prefer-a-sibling-dispatch-over-a-subagent) had both edited the exact regions I touched — including the now-deleted architect doc — so I had to hand-merge their additions into the surface reframe and re-fit everything under the caps again.

Confidence is high: warded architect errors as unknown, the roster renders three roles, the read-only surface still works through the director, and the full suite + pre-commit gate are green. The one thing I could not do in here is the live warded director drain->surface->resume exercise the acceptance criteria call for — no docker-in-container — so thats the open follow-up: someone should run it once against a real backlog to confirm the surface phase behaves end-to-end before fully trusting it in the fleet.

Landed. The core was smaller than it looked: architect and the directors drain-surface were already the *same* `runScratchSession` bring-up, so collapsing them was mostly deletion — unregister the command, rename the file/verb to `directorSurfaceCommand`/`surface`, drop the orphaned `roleArchitect`, and re-point the read-only context block at the heartbeat instead of "the architect." What actually fought back was nothing in the Go — it was the doc-size discipline. Nearly every agent doc sits deliberately a few chars under the 4000-char cap, so every cross-reference I added (and the longer `agent-director-surface.md` filename) tipped 8+ files over at once. I ended up renaming the doc to the shorter `agent-surface.md` and trimming prose char-by-char to claw back budget. Then two rounds of `main` integration: ward#370 (`--org` scope) and ward#374 (prefer-a-sibling-dispatch-over-a-subagent) had both edited the exact regions I touched — including the now-deleted architect doc — so I had to hand-merge their additions into the surface reframe and re-fit everything under the caps again. Confidence is high: `warded architect` errors as unknown, the roster renders three roles, the read-only surface still works through the director, and the full suite + pre-commit gate are green. The one thing I could *not* do in here is the live `warded director` drain->surface->resume exercise the acceptance criteria call for — no docker-in-container — so thats the open follow-up: someone should run it once against a real backlog to confirm the surface phase behaves end-to-end before fully trusting it in the fleet.