---
phase: 11-architect-agent
plan: 01
subsystem: agent
tags: [zod, schema, discriminated-union, agent-mode, typescript]

# Dependency graph
requires:
  - phase: 10-multi-question-schema
    provides: Multi-question Q&A support with batched answers
provides:
  - AgentMode type (execute/discuss/breakdown)
  - Mode-specific output schemas (discuss, breakdown)
  - JSON schemas for Claude CLI --json-schema flag
  - Decision and PhaseBreakdown types for agent outputs
affects: [11-02, 11-03, 11-05, 11-08]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Mode-specific discriminated unions for agent output"
    - "Zod + JSON Schema dual definition for Claude CLI"

key-files:
  created: []
  modified:
    - src/agent/types.ts
    - src/agent/schema.ts
    - src/db/schema.ts
    - src/agent/mock-manager.ts
    - src/events/types.ts
    - src/db/repositories/drizzle/test-helpers.ts

key-decisions:
  - "AgentMode stored in database with 'execute' default for backwards compatibility"
  - "Discuss mode outputs decisions array with topic/decision/reason structure"
  - "Breakdown mode outputs phases array with number/name/description/dependencies"
  - "AgentStoppedEvent reason extended with context_complete and breakdown_complete"

patterns-established:
  - "Mode-specific output schemas follow same discriminated union pattern as execute mode"

# Metrics
duration: 6min
completed: 2026-01-31
---

# Phase 11 Plan 01: Agent Mode Schema Extension Summary

**Extended agent schema with mode field and mode-specific output schemas for discuss/breakdown operations**

## Performance

- **Duration:** 6 min
- **Started:** 2026-01-31T18:01:55Z
- **Completed:** 2026-01-31T18:07:57Z
- **Tasks:** 3
- **Files modified:** 6

## Accomplishments

- Added AgentMode type with three modes: execute (default), discuss, breakdown
- Created discussOutputSchema for context gathering with decisions array output
- Created breakdownOutputSchema for initiative decomposition with phases array output
- Added JSON schema versions for Claude CLI --json-schema flag integration
- Extended MockAgentManager to support mode-specific scenarios

## Task Commits

Each task was committed atomically:

1. **Task 1: Add AgentMode type and database column** - `91e57c6` (feat)
2. **Task 2: Create mode-specific output schemas** - `3f8d6d5` (feat)
3. **Task 3: Update MockAgentManager for mode support** - `0abf02a` (feat)
4. **Fix: Test database schema** - `f7edac7` (fix)

## Files Created/Modified

- `src/agent/types.ts` - Added AgentMode type, mode to SpawnAgentOptions and AgentInfo
- `src/agent/schema.ts` - Added Decision, PhaseBreakdown types; discussOutputSchema, breakdownOutputSchema with JSON schema versions
- `src/db/schema.ts` - Added mode column to agents table
- `src/agent/mock-manager.ts` - Added context_complete and breakdown_complete scenario support
- `src/events/types.ts` - Extended AgentStoppedEvent reason type
- `src/db/repositories/drizzle/test-helpers.ts` - Added mode column to test database schema
- `drizzle/0000_bizarre_naoko.sql` - Generated migration for mode column

## Decisions Made

1. **11-01: Mode defaults to 'execute'** - Backwards compatible with existing agents
2. **11-01: Discuss output captures decisions array** - Topic/decision/reason structure for context refinement
3. **11-01: Breakdown output captures phases array** - Number/name/description/dependencies for initiative decomposition
4. **11-01: Shared questionItemSchema exported** - Reusable across all modes for Q&A

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Fixed test database schema missing mode column**
- **Found during:** Task 1 verification
- **Issue:** Test database CREATE_TABLES_SQL did not include the new mode column
- **Fix:** Added `mode TEXT NOT NULL DEFAULT 'execute'` to agents table in test-helpers.ts
- **Files modified:** src/db/repositories/drizzle/test-helpers.ts
- **Verification:** All 384 tests pass
- **Committed in:** f7edac7

---

**Total deviations:** 1 auto-fixed (1 blocking)
**Impact on plan:** Required for tests to pass. No scope creep.

## Issues Encountered

None

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- Mode infrastructure complete and ready for 11-02 (Initiative & Phase Repositories)
- JSON schemas ready for Claude CLI integration in 11-03
- MockAgentManager ready for E2E testing in 11-08

---
*Phase: 11-architect-agent*
*Completed: 2026-01-31*
