# REQ-002: Deprecate CLI Commands

## Metadata
- **Status:** implemented
- **Priority:** high
- **Dependencies:** REQ-000
- **Created:** 2026-03-03
- **Implemented:** 2026-03-03

## Context

iEvo is transitioning from a command-oriented model to a TUI-first autonomous model. CLI commands that are now superseded (by the TUI, HR agent, or internal orchestration) must show deprecation warnings so users know the direction, while still functioning to avoid breaking existing scripts and workflows.

**Design decision:** commands must continue to work — they just warn. Removal happens in a future release.

**Deprecated commands and their replacements:**

| Command | Replacement |
|---------|-------------|
| `ievo init` | Run `ievo` — auto-init with confirmation |
| `ievo add` | HR agent (automatic agent composition) |
| `ievo remove` | HR agent |
| `ievo update` | HR agent |
| `ievo list` | TUI dashboard (Agents tab) |
| `ievo run` | TUI dashboard |
| `ievo team` | Removed (no replacement) |
| `ievo orchestrate` | Internal pipeline (no user-facing replacement) |
| `ievo learn *` | TUI Evolution tab (automatic) |
| `ievo deps *` | Automatic during agent install |
| `ievo dev *` | Removed |

**Only `ievo config` remains active (not deprecated).**

**Implementation details:**

`deprecated_command()` utility in `src/ievo/utils/deprecation.py`:
```python
def deprecated_command(name: str, alternative: str | None = None) -> None:
    msg = f"[bold]{name}[/bold] is deprecated and will be removed in a future release."
    if alternative:
        msg += f" Use {alternative} instead."
    warn(msg)
```

Each deprecated command function calls `deprecated_command()` at the top of its body, before doing any work. Example:
```python
def add(...):
    deprecated_command("ievo add", alternative="the HR agent (automatic agent composition)")
    add_agents(agents)
```

Help strings in `cli.py` are marked with `[dim][DEPRECATED][/dim]` prefix.

**`add` command special case:** the underlying logic is split into two functions:
- `add_agents(agents: list[str])` — internal API, no warning, called by HR agent programmatically
- `add(agents: ...)` — CLI wrapper, emits deprecation warning, then calls `add_agents()`

This pattern keeps the internal API clean while the CLI surface is deprecated.

## Acceptance Criteria

- [x] `ievo init .` → prints deprecation warning containing "ievo init" and "deprecated" before doing any work
- [x] `ievo init .` → still creates project files after printing the warning (command still works)
- [x] `ievo add <agent>` → prints deprecation warning mentioning "ievo add" and "HR agent"
- [x] `ievo add <agent>` → still installs the agent after the warning
- [x] `deprecated_command("ievo add", alternative="the HR agent")` → warning message contains command name, "deprecated", "removed in a future release", and alternative
- [x] `deprecated_command("ievo learn")` (no alternative) → warning contains command name and "deprecated" but NOT the word "instead"
- [x] `add_agents(agents)` called directly (internal API) → NO deprecation warning emitted
- [x] `ievo --help` → all deprecated commands show `[DEPRECATED]` in their help text
- [x] `ievo config` → no deprecation warning (active command)

## Negative Acceptance Criteria

- Does NOT prevent deprecated commands from executing their actual logic
- Does NOT exit with error after showing the deprecation warning
- Does NOT remove the deprecated commands from the CLI (they are still registered)
- `add_agents()` (internal function) does NOT call `deprecated_command()` — warning is only in the CLI wrapper `add()`
- Does NOT affect `ievo config` in any way

## Technical Notes

Files: `src/ievo/utils/deprecation.py` (new), `src/ievo/cli.py`, `src/ievo/commands/init.py`, `src/ievo/commands/add.py`, `src/ievo/commands/remove.py`, `src/ievo/commands/update.py`, `src/ievo/commands/list_cmd.py`, `src/ievo/commands/run.py`, `src/ievo/commands/team.py`, `src/ievo/commands/orchestrate.py`, `src/ievo/commands/learn.py`, `src/ievo/commands/deps.py`, `src/ievo/commands/dev.py`

Tests: `tests/test_deprecation.py` (`test_with_alternative`, `test_without_alternative`, `test_message_mentions_future_removal`), plus per-command deprecation tests in their respective test files.
