diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 2118e31..04fddd8 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -146,11 +146,10 @@ Plans: **Goal**: Define structured agent output schema (done/question/error discriminated union) and update ClaudeAgentManager to use `--json-schema` flag for validated output parsing **Depends on**: Phase 8 **Research**: Unlikely (Zod schemas, Claude CLI flags documented) -**Plans**: 2 plans +**Plans**: 1 plan Plans: -- [ ] 08.1-01: Agent Output Schema & ClaudeAgentManager -- [ ] 08.1-02: MockAgentManager Schema Alignment +- [x] 08.1-01: Agent Output Schema & ClaudeAgentManager #### Phase 9: Extended Scenarios @@ -179,7 +178,7 @@ Phases execute in numeric order: 1 → 1.1 → 2 → 3 → 4 → 5 → 6 → 7 | 6. Coordination | v1.0 | 3/3 | Complete | 2026-01-30 | | 7. Mock Agent & Test Harness | v1.1 | 2/2 | Complete | 2026-01-31 | | 8. E2E Scenario Tests | v1.1 | 2/2 | Complete | 2026-01-31 | -| 8.1. Agent Output Schema | v1.1 | 0/2 | Not started | - | +| 8.1. Agent Output Schema | v1.1 | 1/1 | Complete | 2026-01-31 | | 9. Extended Scenarios | v1.1 | 0/2 | Not started | - | --- diff --git a/.planning/STATE.md b/.planning/STATE.md index d654b65..0a5c02e 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -9,19 +9,19 @@ See: .planning/PROJECT.md (updated 2026-01-30) ## Current Position -Phase: 8 of 9 (E2E Scenario Tests) -Plan: 2 of 2 in current phase +Phase: 8.1 of 9 (Agent Output Schema) +Plan: 1 of 1 in current phase Status: Phase complete -Last activity: 2026-01-31 — Completed 08-02-PLAN.md +Last activity: 2026-01-31 — Completed 08.1-01-PLAN.md -Progress: ████████░░ 80% +Progress: █████████░ 85% ## Performance Metrics **Velocity:** -- Total plans completed: 31 +- Total plans completed: 32 - Average duration: 3 min -- Total execution time: 96 min +- Total execution time: 101 min **By Phase (v1.0):** @@ -36,7 +36,7 @@ Progress: ████████░░ 80% | 6 | 3/3 | 9 min | 3 min | **Recent Trend:** -- Last 5 plans: 08-02 (3 min), 08-01 (3 min), 07-02 (4 min), 07-01 (2 min), 06-03 (3 min) +- Last 5 plans: 08.1-01 (5 min), 08-02 (3 min), 08-01 (3 min), 07-02 (4 min), 07-01 (2 min) - Trend: Steady ## Accumulated Context @@ -110,6 +110,9 @@ Recent decisions affecting current work: - 08-02: Agent crash tests verify task stays in_progress (not completed) - 08-02: Merge conflict tests require manual agentRepository seeding - 08-02: MockWorktreeManager setMergeResult for conflict scenarios +- 08.1-01: Discriminated union with done/question/unrecoverable_error for agent output +- 08.1-01: JSON schema passed to Claude CLI for validated output +- 08.1-01: Options and multiSelect fields for structured question choices ### Pending Todos @@ -129,5 +132,5 @@ None yet. ## Session Continuity Last session: 2026-01-31 -Stopped at: Completed 08-02-PLAN.md (Phase 8 complete) +Stopped at: Completed 08.1-01-PLAN.md (Phase 8.1 complete) Resume file: None diff --git a/.planning/phases/08.1-agent-output-schema/08.1-01-SUMMARY.md b/.planning/phases/08.1-agent-output-schema/08.1-01-SUMMARY.md new file mode 100644 index 0000000..c604c2e --- /dev/null +++ b/.planning/phases/08.1-agent-output-schema/08.1-01-SUMMARY.md @@ -0,0 +1,104 @@ +--- +phase: 08.1-agent-output-schema +plan: 01 +subsystem: agent +tags: [zod, json-schema, discriminated-union, claude-cli] + +# Dependency graph +requires: + - phase: 04 + provides: [AgentManager interface, ClaudeAgentManager adapter] +provides: + - Structured agent output schema with Zod validation + - JSON schema for Claude CLI --json-schema flag + - Explicit question/resume flow via status field + - PendingQuestion type for structured question data +affects: [coordination, dispatch, cli] + +# Tech tracking +tech-stack: + added: [] + patterns: [discriminated-union-for-status, json-schema-cli-integration] + +key-files: + created: [src/agent/schema.ts] + modified: [src/agent/manager.ts, src/agent/types.ts, src/agent/mock-manager.ts, src/events/types.ts] + +key-decisions: + - "Discriminated union with done/question/unrecoverable_error status" + - "JSON schema passed to CLI for validated output" + - "Options and multiSelect fields for structured question choices" + +patterns-established: + - "Agent output schema: use discriminated union on status field" + - "CLI integration: pass --json-schema for structured output" + +# Metrics +duration: 5min +completed: 2026-01-31 +--- + +# Phase 08.1 Plan 01: Agent Output Schema Summary + +**Structured agent output with Zod discriminated union for explicit done/question/error signaling via --json-schema CLI flag** + +## Performance + +- **Duration:** 5 min +- **Started:** 2026-01-31T14:20:00Z +- **Completed:** 2026-01-31T14:25:31Z +- **Tasks:** 3 +- **Files modified:** 7 + +## Accomplishments + +- Created Zod schema with discriminated union (done/question/unrecoverable_error) +- ClaudeAgentManager now passes --json-schema to Claude CLI for validated output +- Agent question flow uses explicit status field instead of hacky string matching +- AgentWaitingEvent includes structured options and multiSelect for rich question UI + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Define agent output schema** - `41598f5` (feat) +2. **Task 2: Update ClaudeAgentManager** - `d9673d5` (feat) +3. **Task 3: Update AgentWaitingEvent** - `3a3d3f4` (feat) + +## Files Created/Modified + +- `src/agent/schema.ts` - Zod schema and JSON schema export for agent output +- `src/agent/manager.ts` - ClaudeAgentManager with --json-schema and structured parsing +- `src/agent/types.ts` - PendingQuestion type and getPendingQuestion interface method +- `src/agent/mock-manager.ts` - MockAgentManager with getPendingQuestion and options support +- `src/agent/manager.test.ts` - Updated tests for new CLI args and result format +- `src/events/types.ts` - AgentWaitingEvent with options and multiSelect fields +- `src/dispatch/manager.test.ts` - Mock updated with getPendingQuestion + +## Decisions Made + +1. **Discriminated union on status** - Chose done/question/unrecoverable_error as the three status values to cover all agent outcomes explicitly +2. **Dual schema export** - Both Zod (runtime validation) and JSON Schema (CLI flag) for maximum flexibility +3. **Options in event payload** - Include question options in AgentWaitingEvent so consumers can render UI without calling getPendingQuestion + +## Deviations from Plan + +None - plan executed exactly as written. + +## Issues Encountered + +None. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +- Schema is ready for use by Phase 9 (CLI commands) +- MockAgentManager supports structured questions for testing +- All verification checks pass + +--- +*Phase: 08.1-agent-output-schema* +*Completed: 2026-01-31*