CLI word "agent" is overloaded — role vs hired forge user #851

New issue

Open

opened 2026-04-16 10:09:59 +00:00 by dev-bot · 0 comments

dev-bot commented

2026-04-16 10:09:59 +00:00

Collaborator

Problem

The word "agent" is overloaded across the disinto CLI:

disinto hire-an-agent <name> <role> → <name> is a forge user (e.g. dev-qwen) that becomes a sidecar container.
disinto agent enable <name> / disable <name> → <name> is a role (e.g. dev, reviewer, gardener, …).

Consequences:

disinto agent enable dev-qwen returns Error: unknown agent 'dev-qwen' — confusing, since hire-an-agent dev-qwen just succeeded with the same string.
Documentation must repeatedly disambiguate "agent (as in role)" vs "agent (as in hired user)".
Future commands (e.g. rotate, remove, status) inherit the ambiguity.

Proposal (for discussion)

Pick one meaning for "agent" and rename the other:

Option A: "agent" = hired sidecar instance. Rename role subcommand to disinto role enable dev.
Option B: "agent" = role (current state-file semantics). Rename hire-an-agent to disinto worker hire <name> <role> or similar.

Option A feels more natural — "agent" as a concrete running entity matches the disinto-agents-llama container name and the [agents.X] TOML block. Role is a property of the agent, not an agent itself.

Either way, need a deprecation plan for the renamed subcommand (alias + warning, one release) and doc updates.

Acceptance

Single, documented meaning for "agent" across CLI, docs, and TOML.
disinto --help and docs disambiguated.
Deprecation path for the renamed subcommand so existing scripts/muscle memory keeps working during transition.

Labeled vision rather than backlog because this is a naming/design decision with user-visible API impact; requires deliberate discussion before implementation.

Related: #845, #846, #847.

## Problem The word "agent" is overloaded across the `disinto` CLI: - `disinto hire-an-agent <name> <role>` → `<name>` is a **forge user** (e.g. `dev-qwen`) that becomes a sidecar container. - `disinto agent enable <name>` / `disable <name>` → `<name>` is a **role** (e.g. `dev`, `reviewer`, `gardener`, …). Consequences: - `disinto agent enable dev-qwen` returns `Error: unknown agent 'dev-qwen'` — confusing, since `hire-an-agent dev-qwen` just succeeded with the same string. - Documentation must repeatedly disambiguate "agent (as in role)" vs "agent (as in hired user)". - Future commands (e.g. rotate, remove, status) inherit the ambiguity. ## Proposal (for discussion) Pick one meaning for "agent" and rename the other: - **Option A:** "agent" = hired sidecar instance. Rename role subcommand to `disinto role enable dev`. - **Option B:** "agent" = role (current state-file semantics). Rename `hire-an-agent` to `disinto worker hire <name> <role>` or similar. Option A feels more natural — "agent" as a concrete running entity matches the `disinto-agents-llama` container name and the `[agents.X]` TOML block. Role is a property of the agent, not an agent itself. Either way, need a deprecation plan for the renamed subcommand (alias + warning, one release) and doc updates. ## Acceptance - Single, documented meaning for "agent" across CLI, docs, and TOML. - `disinto --help` and docs disambiguated. - Deprecation path for the renamed subcommand so existing scripts/muscle memory keeps working during transition. Labeled `vision` rather than `backlog` because this is a naming/design decision with user-visible API impact; requires deliberate discussion before implementation. Related: #845, #846, #847.