disinto-ops/sprints/agent-role-disambiguation.md

Sprint: agent-role-disambiguation

Vision issues

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

What this enables

A single, unambiguous meaning for "agent" across the CLI, docs, and TOML. disinto agent will no longer confuse users who just hired an agent via hire-an-agent and then get Error: unknown agent when they try to enable it by the same name. Future commands (rotate, remove, status) can be added without inheriting the ambiguity.

What exists today

• disinto hire-an-agent <name> <role> creates a forge user (instance) — implemented in lib/hire-agent.sh, referenced in 6 files / 17 occurrences.
• disinto agent {enable,disable,status} manages a hardcoded list of 6 roles (dev, reviewer, gardener, architect, planner, predictor) via state files in state/.<role>-active — implemented in bin/disinto lines 2540-2666.
• lib/guard.sh checks state files to gate polling loops.
• [agents.X] TOML sections and agents-<name> docker-compose services use "agent" to mean instance (matching hire-an-agent semantics).
• docker/agents/entrypoint.sh uses AGENT_ROLES env var to route roles to scripts.
• docs/agents-llama.md documents the hiring flow (8 references to hire-an-agent).
• Existing sprint agent-management-redesign.md (#557) redesigns hiring UX but does not address the naming overload.

Complexity

• 3 files changed substantively: bin/disinto (dispatch + help), lib/guard.sh (help text comment), docs/agents-llama.md
• ~3 sub-issues
• 95% gluecode (rename + alias), 5% greenfield (deprecation warning logic)

Risks

• Script breakage: Users or automation calling disinto agent enable dev will break without a deprecation shim. Mitigated by alias + warning for one release cycle.
• Incomplete rename: Missing a reference in help text or docs leaves partial ambiguity. Mitigated by grep-sweep acceptance criterion.
• Sprint overlap with #557: The agent-management-redesign sprint touches the same CLI surface. This sprint should land first so #557 builds on clean terminology.

Cost — new infra to maintain

• One deprecation alias in bin/disinto (temporary — removed after one release cycle)
• No new services, scheduled tasks, formulas, or agent roles

Recommendation

Worth it. This is a small, low-risk naming fix that unblocks cleaner UX for future agent management work (#557, #845-#847). The overload is already causing user-facing errors. Option A ("agent" = instance, rename role subcommand to disinto role) aligns with existing TOML ([agents.X]) and container naming (agents-<name>), minimizing total churn.

Design decisions

Q1: New subcommand name

What replaces disinto agent {enable,disable,status}?

• A) disinto role — matches AGENT_ROLES naming, short, clear
• B) disinto service — emphasizes polling-loop service aspect
• C) disinto module — neutral, less intuitive for enable/disable

Q2: Internal variable rename scope

Rename CLI surface only, or also internal identifiers?

• A) CLI only — keep AGENT_ROLES, state files, function names unchanged
• B) Full rename — AGENT_ROLES→ACTIVE_ROLES, state files, function names

Q3: Deprecation shim removal timing

When does the old disinto agent alias get removed?

• A) After #557 (agent-management-redesign) merges
• B) Calendar-based: 30 days after merge
• C) Never — keep alias permanently

Sub-issues

• id: rename-agent-subcommand-to-role title: "vision(#851): rename disinto agent subcommand to disinto role" labels: [backlog] depends_on: [] body: |

  Goal

  Rename the disinto agent {enable,disable,status} CLI subcommand to disinto role {enable,disable,status} so "agent" consistently means a hired forge user (instance) across the CLI.

  Acceptance criteria

  • disinto role enable dev, disinto role disable dev, disinto role status work identically to the old disinto agent equivalents
  • disinto role enable --all and disinto role disable --all work
  • disinto agent enable dev still works but prints a deprecation warning to stderr: Warning: 'disinto agent' is deprecated, use 'disinto role' instead
  • disinto --help shows role as the primary subcommand and does not list agent as a top-level subcommand for role management
  • grep -r 'disinto agent enable\|disinto agent disable\|disinto agent status' bin/ lib/ docs/ returns zero hits outside the deprecation shim itself

• id: update-docs-agent-terminology title: "vision(#851): update docs to disambiguate agent vs role" labels: [backlog] depends_on: [rename-agent-subcommand-to-role] body: |

  Goal

  Update all user-facing documentation so "agent" means hired forge user (instance) and "role" means the abstract capability (dev, reviewer, gardener, etc.).

  Acceptance criteria

  • docs/agents-llama.md uses "role" when referring to enable/disable and "agent" only for the hired instance
  • AGENTS.md agent table and label conventions use consistent terminology
  • lib/guard.sh inline comments updated
  • disinto --help full output uses "role" for enable/disable, "agent" for hire-an-agent
  • No doc sentence uses "agent" to mean both instance and role in the same paragraph

• id: remove-agent-deprecation-shim title: "vision(#851): remove deprecated disinto agent alias after transition period" labels: [backlog] depends_on: [rename-agent-subcommand-to-role] body: |

  Goal

  Remove the disinto agent → disinto role deprecation alias after one release cycle, completing the rename.

  Acceptance criteria

  • disinto agent enable dev returns a clear error: Unknown command 'agent'. Did you mean 'role'?
  • No deprecation shim code remains in bin/disinto
  • CHANGELOG or commit message notes the breaking change