diff --git a/sprints/agent-role-disambiguation.md b/sprints/agent-role-disambiguation.md new file mode 100644 index 0000000..15df1b6 --- /dev/null +++ b/sprints/agent-role-disambiguation.md @@ -0,0 +1,101 @@ +# 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 ` 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/.-active` — implemented in `bin/disinto` lines 2540-2666. +- `lib/guard.sh` checks state files to gate polling loops. +- `[agents.X]` TOML sections and `agents-` 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-`), 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 +