diff --git a/sprints/agent-role-disambiguation.md b/sprints/agent-role-disambiguation.md deleted file mode 100644 index 15df1b6..0000000 --- a/sprints/agent-role-disambiguation.md +++ /dev/null @@ -1,101 +0,0 @@ -# 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 -