---
phase: 04-agent-lifecycle
plan: 04
subsystem: agent
tags: [trpc, cli, commander, agent-management]

# Dependency graph
requires:
  - phase: 04-01
    provides: Agent schema and DrizzleAgentRepository
  - phase: 04-02
    provides: AgentManager port interface and lifecycle events
  - phase: 04-03
    provides: ClaudeAgentManager adapter implementation
provides:
  - Agent tRPC procedures for spawn, stop, list, get, resume, getResult
  - CLI commands for full agent lifecycle management
  - Type-safe client-server communication for agents
affects: [05-task-dispatch, user-facing-cli]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "tRPC input schemas with Zod refinement for name/id lookup"
    - "CLI subcommand pattern with commander.js"
    - "Optional context dependencies for gradual integration"

key-files:
  created: []
  modified:
    - src/trpc/context.ts
    - src/trpc/router.ts
    - src/server/trpc-adapter.ts
    - src/cli/index.ts

key-decisions:
  - "AgentManager optional in tRPC context until full server wiring"
  - "Agent identifier schema supports both name and id lookup with refinement"
  - "CLI uses human-readable names as primary identifier (matches gastown pattern)"
  - "Helper functions for consistent error handling in procedures"

# Metrics
duration: 3 min
completed: 2026-01-30
---

# Phase 04 Plan 04: tRPC Integration & CLI Commands Summary

**Agent tRPC procedures and CLI commands enabling full agent lifecycle management via cw agent spawn/stop/list/get/resume/result**

## Performance

- **Duration:** 3 min
- **Started:** 2026-01-30T19:09:59Z
- **Completed:** 2026-01-30T19:13:25Z
- **Tasks:** 3
- **Files modified:** 4

## Accomplishments

- Added AgentManager to tRPC context with optional type for gradual integration
- Implemented 7 agent tRPC procedures: spawn, stop, listAgents, getAgent, getAgentByName, resumeAgent, getAgentResult
- Built full CLI command suite: cw agent spawn/stop/list/get/resume/result
- All agent commands use tRPC client for type-safe communication

## Task Commits

Each task was committed atomically:

1. **Task 1: Add AgentManager to tRPC context** - `acf3b8d` (feat)
2. **Task 2: Add agent procedures to tRPC router** - `16f85cd` (feat)
3. **Task 3: Add agent CLI commands** - `4d89160` (feat)

## Files Created/Modified

- `src/trpc/context.ts` - Added optional agentManager to TRPCContext and CreateContextOptions
- `src/trpc/router.ts` - Added 7 agent procedures with Zod input schemas
- `src/server/trpc-adapter.ts` - Added agentManager pass-through to context
- `src/cli/index.ts` - Replaced placeholder with full agent subcommand suite

## Decisions Made

1. **AgentManager optional in context** - Allows gradual server integration without breaking existing code
2. **Agent identifier schema with refinement** - z.refine() ensures either name OR id is provided
3. **Names as primary CLI identifier** - Matches the gastown/chinatown naming pattern from architecture
4. **requireAgentManager helper** - Consistent error handling when manager unavailable

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Phase 4 (Agent Lifecycle) is now complete
- All 4 plans finished: schema, port, adapter, integration
- All verification checks pass:
  - npm run build succeeds
  - npm test passes 240 tests
  - cw agent --help shows all 6 commands
  - Agent procedures accessible via tRPC client
- Requirements satisfied:
  - AGENT-01: Spawn via cw agent spawn --name <name> --task <taskId> <prompt>
  - AGENT-02: Stop via cw agent stop <name>
  - AGENT-03: List via cw agent list
  - AGENT-04: Resume via cw agent resume <name> <response>
  - AGENT-05: Background mode (inherent in subprocess model)
  - AGENT-07: JSON output via CLI --output-format json
- Ready for Phase 5: Task Dispatch

---
*Phase: 04-agent-lifecycle*
*Completed: 2026-01-30*
