# Agent File Rename Plan

## Goal

Unify `pkg/agent/` package file naming to resolve the `loop_*` prefix naming confusion and unclear responsibility boundaries.

## Change Overview

### File Renames (12 files)

| Original | New | Description |
|----------|-----|-------------|
| `loop.go` | `agent.go` | AgentLoop main body + lifecycle methods |
| `loop_message.go` | `agent_message.go` | Message handling and routing |
| `loop_outbound.go` | `agent_outbound.go` | Response publishing |
| `loop_event.go` | `agent_event.go` | Event system |
| `loop_command.go` | `agent_command.go` | Command processing |
| `loop_steering.go` | `agent_steering.go` | Steering message handling |
| `loop_transcribe.go` | `agent_transcribe.go` | Audio transcription |
| `loop_media.go` | `agent_media.go` | Media processing |
| `loop_mcp.go` | `agent_mcp.go` | MCP initialization |
| `loop_utils.go` | `agent_utils.go` | Utility functions |
| `loop_inject.go` | `agent_inject.go` | Dependency injection |
| `loop_turn.go` | `turn_coord.go` | Turn coordinator |

### File Merges (2 → 1)

| Original | New | Description |
|----------|-----|-------------|
| `turn.go` + `turn_exec.go` | `turn_state.go` | Turn-related type definitions |

## Final File Structure

```
pkg/agent/
├── agent.go              # AgentLoop + Run/Stop/Close lifecycle
├── agent_message.go     # Message processing
├── agent_outbound.go    # Response publishing
├── agent_event.go       # Event system
├── agent_command.go     # Command processing
├── agent_steering.go    # Steering
├── agent_transcribe.go  # Transcription
├── agent_media.go       # Media processing
├── agent_mcp.go         # MCP
├── agent_utils.go       # Utility functions
├── agent_inject.go      # Dependency injection
├── turn_coord.go       # runTurn + coordinator
├── turn_state.go       # turnState + turnExecution + Control + ToolControl + LLMPhase
├── pipeline.go         # Pipeline struct + NewPipeline
├── pipeline_setup.go
├── pipeline_llm.go
├── pipeline_execute.go
└── pipeline_finalize.go
```

## Naming Convention

| Prefix | Content | Example |
|--------|---------|---------|
| `agent_*` | AgentLoop method files | `agent_message.go`, `agent_event.go` |
| `turn_*` | Turn lifecycle related | `turn_coord.go`, `turn_state.go` |
| `pipeline_*` | Pipeline methods | `pipeline_setup.go`, `pipeline_llm.go` |
| `context_*` | Context management | `context_manager.go`, `context_legacy.go` |
| `hook_*` | Hook system | `hook_process.go`, `hook_mount.go` |

## Architecture Layers

```
┌─────────────────────────────────────────────────────────┐
│                    AgentLoop (agent.go)                │
│  - Message loop Run/Stop/Close                        │
│  - Dependency injection (agent_inject.go)             │
│  - Message routing (agent_message.go)                 │
│  - Response publishing (agent_outbound.go)            │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Turn Coordinator (turn_coord.go)          │
│  - runTurn(): main coordinator                         │
│  - abortTurn(): abort                                 │
│  - askSideQuestion(): side question                   │
│  - selectCandidates(): model selection                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                 Pipeline (pipeline_*.go)               │
│  - SetupTurn(): initialization                        │
│  - CallLLM(): LLM call                               │
│  - ExecuteTools(): tool execution                     │
│  - Finalize(): finalization                          │
└─────────────────────────────────────────────────────────┘
```

## Verification Results

- ✅ `go build ./pkg/agent/...` - Pass
- ✅ `go vet ./pkg/agent/...` - No warnings
- ✅ `go test ./pkg/agent/... -skip "TestSeahorse|TestGlobalSkillFileContentChange"` - Pass