# Orchestrator Operations (Copilot CLI)

Task IDs, `kill`, `purge`, `resume` and the `status` table for the Copilot CLI
orchestrator skill. The shared operational contract both CLIs follow is
`$HOME/.claude/multi-agent-refs/phases/operations.md`; read it alongside this file.
Pickers follow `$HOME/.claude/multi-agent-refs/picker-contract.md`: never a one-option
call, and branch on the option selected, not on its text.

## Task ID System

Every task gets an **auto-incremented short ID** for easy reference:

```
multi-agent "PROJ-12345" "feature/PROJ-12345-order-filter"
→ ✅ Task #1 started  -  PROJ-12345
multi-agent "PROJ-67890" "feature/PROJ-67890-checkout-flow"
→ ✅ Task #2 started  -  PROJ-67890
```

ID is stored in `agent-state.json` and shown in `multi-agent status`. ID counter
stored at `$HOME/.claude/logs/multi-agent/{project}/.counter` (persists across sessions, shared with
every host).

## Kill Logic

When `multi-agent kill [id]` is called:

1. **Find task**: Look up task by short ID (e.g. `#2`) or Jira ID (e.g. `PROJ-67890`)
2. **Confirm**: Ask user: `"PROJ-67890 (Task #2) will be deleted: worktree and branch. Logs will be preserved. Are you sure?"`
3. **Stop agents**: Kill any running background agents for this task
4. **Delete worktree**: `git worktree remove .worktrees/PROJ-{id} --force`
5. **Delete branch**: `git branch -D {branch-name}`
6. **Delete remote branch**: ONLY if user explicitly confirms: "Do you want to delete the remote branch too?"
7. **Keep the logs**: they live in `$HOME/.claude/logs/multi-agent/{project}/{task-id}/`, outside the worktree, and are not deleted with it
8. **Confirm**: `❌ Task #2 (PROJ-67890) killed  -  worktree and branch removed (logs preserved)`

## Purge (Full Reset)

When `multi-agent purge` is called:

1. **Confirm**: `"⚠️ WARNING: All worktrees, branches, logs and state will be deleted. This cannot be undone. Are you sure?"`
2. **List**: Show what will be deleted:
   ```
   To be deleted:
   - .worktrees/PROJ-12345/ (branch: feature/PROJ-12345-...)
   - .worktrees/PROJ-67890/ (branch: feature/PROJ-67890-...)
   - $HOME/.claude/logs/multi-agent/{project}/.counter
   Total: 2 worktrees, 2 branches, 2 logs
   ```
3. **Second confirm** (paranoia gate)  -  a native `AskUserQuestion` picker (no typed keyword):
   - `question`: "This is irreversible. Permanently wipe every worktree, branch, log, and state file now?" (`outputLanguage`)
   - `header`: "Purge" (English, <=12 chars) · `options` (label + description in `outputLanguage`; the names below are the option SEMANTICS, not strings to print): option 1 "Purge permanently"  -  delete all worktrees, branches, logs, and state; option 2 "Cancel"  -  abort, change nothing
   - Anything other than **Purge permanently** → cancel.
4. **Execute** (for each worktree):
   - `git worktree remove .worktrees/PROJ-{id} --force`
   - `git branch -D {branch-name}`
   - Remote branch delete ONLY if user explicitly confirms: "Do you want to delete the remote branches too?"
5. **Cleanup**: Remove `.worktrees/.multi-agent-counter` and `.worktrees/.archive/`
6. **Confirm**:
   ```
   🔥 Purge complete
   Deleted: {N} worktrees, {N} branches, {N} logs
   multi-agent is reset to clean state
   ```

## Resume Logic

When `multi-agent resume [id]` is called:

1. **Find state file**: `$HOME/.claude/logs/multi-agent/{project}/{task-id}/agent-state.json`  -  that is where Phase 0 writes it, not inside the worktree. A task finalized by Phase 4 keeps its state at `.../{task-id}/artifacts/agent-state.json`, so look there too before reporting not-found.
   - If no `id` given, take the most recent task dir with `status != "done"`
2. **Read state**: Parse `agent-state.json` → determine last completed phase
3. **Restore context**: Read `agent-log.md` for previous findings:
   - Phase 1 analysis findings → reuse in Phase 2+ (Dev onwards)
   - Phase 1 plan/todos → reuse in Phase 2+
   - Phase 2 code changes → already on disk in worktree
   - Phase 3 review findings → reuse if re-reviewing
4. **Resume from next phase**: Skip completed phases, start from `currentPhase + 1`
5. **Log**: `🔄 Resumed PROJ-{id} from Phase {N}`

This works across sessions because all state is file-based: `agent-state.json`
persists phase progress, `agent-log.md` persists findings, analysis and decisions,
and the git worktree persists code changes. Nothing depends on in-memory session.

## Status Display Format

When `multi-agent status` is called, show:

```
🤖 Multi-Agent Tasks

| ID | Jira | Branch | Phase | Status | Duration |
|----|------|--------|-------|--------|----------|
| #1 | PROJ-12345 | feature/PROJ-12345-... | 2/5 Dev | ⚡ todo-2 in progress | 4m |
| #2 | PROJ-67890 | feature/PROJ-67890-... | 3/5 Review | 🔍 Waiting consensus | 7m |
| #3 | PROJ-11111 | feature/PROJ-11111-... | 5/5 DONE | ✅ Complete | 12m |

💡 kill #2  |  log #1  |  resume #3
```