Codewalkers/.planning/STATE.md

# Project State

## Project Reference

See: .planning/PROJECT.md (updated 2026-02-04)

**Core value:** Coordinate multiple Claude Code agents without losing track or stepping on each other.
**Current focus:** v2.0 Frontend — Build web UI from wireframes

## Current Position

Phase: 21 of 21 (Polish & Integration) - In progress
Plan: 5 of 6 in current phase
Status: Completed 21-05 (Code Splitting & Data-Fetching Performance)
Last activity: 2026-02-05 - Completed 21-05-PLAN.md (route code splitting + PlanTasksFetcher fix)

Progress: █████████░ 99%

## Performance Metrics

**Velocity:**
- Total plans completed: 74
- Average duration: 3 min
- Total execution time: 209 min

**By Phase (v1.0):**

| Phase | Plans | Total | Avg/Plan |
|-------|-------|-------|----------|
| 1 | 5/5 | 15 min | 3 min |
| 1.1 | 6/6 | 15 min | 3 min |
| 2 | 2/2 | 8 min | 4 min |
| 3 | 2/2 | 7 min | 4 min |
| 4 | 4/4 | 12 min | 3 min |
| 5 | 5/5 | 18 min | 4 min |
| 6 | 3/3 | 9 min | 3 min |

**Recent Trend:**
- Last 5 plans: 10-03 (4 min), 10-02 (4 min), 10-01 (5 min), 09-02 (3 min), 09-01 (3 min)
- Trend: Steady

## Accumulated Context

### Decisions

Decisions are logged in PROJECT.md Key Decisions table.
Recent decisions affecting current work:

- 01-01: Merged Tasks 1 and 2 since build verification required source files
- 01-02: Task 2 required no code changes - existing bin config was correct
- 01-04: Log directory structure ~/.cw/logs/{processId}/ with timestamp prefixes
- 01-05: Used node:http instead of Express for minimal server footprint
- 01.1-01: EventBus is PORT, EventEmitterBus is ADAPTER for swappability
- 01.1-02: Zod for output validation, procedures match HTTP endpoint shapes
- 01.1-03: Optional eventBus parameter for ProcessManager, events emitted synchronously
- 01.1-04: EventBus is optional parameter for backwards compatibility in logging
- 01.1-05: Optional eventBus injection for server lifecycle events
- 01.1-06: Use @trpc/server/adapters/fetch for HTTP handling, keep HTTP endpoints for curl
- 02-01: Factory function for database (not singleton) allows isolated test instances
- 02-01: WAL mode enabled for better concurrent read performance
- 02-01: Separate task_dependencies table for many-to-many task relationships
- 02-02: Repository per aggregate (one interface/adapter per table)
- 02-02: Port-adapter pattern for repositories (same as EventBus)
- 02-02: Fetch after insert to ensure schema defaults applied
- 03-01: WorktreeManager as PORT interface - same pattern as EventBus
- 03-01: Four git events for full worktree lifecycle (create, remove, merge, conflict)
- 03-02: Worktrees stored in .cw-worktrees directory within repository
- 03-02: createTestRepo() helper for git integration tests
- 04-02: AgentManager as PORT interface following hexagonal pattern
- 04-02: Human-readable agent names (gastown, chinatown) in addition to IDs
- 04-02: AgentStatus includes 'waiting_for_input' for AskUserQuestion pauses
- 04-02: Five agent events covering full lifecycle
- 04-01: Agent name unique human-readable identifier
- 04-01: taskId nullable with SET NULL (agent may outlive task)
- 04-01: sessionId nullable - populated from CLI JSON after first run
- 04-01: CreateAgentData interface for explicit optional fields
- 04-03: Use Claude CLI with --output-format json (not SDK streaming)
- 04-03: Extract session_id from JSON result for --resume capability
- 04-03: Use agent.id from repository for activeAgents tracking
- 04-04: AgentManager optional in tRPC context until full server wiring
- 04-04: Agent identifier schema supports both name and id lookup with refinement
- 04-04: CLI uses human-readable names as primary identifier
- 05-03: DispatchManager as PORT interface following hexagonal pattern
- 05-03: QueuedTask includes dependsOn array for dependency tracking
- 05-03: Four dispatch events mirror agent lifecycle events
- 05-02: TaskRepository optional in tRPC context (same pattern as AgentManager)
- 05-02: listTasks requires planId (no global task listing)
- 05-02: Task status limited to: pending, in_progress, completed, blocked
- 05-01: Sender/recipient pattern with type enum and nullable ID for agent-user communication
- 05-01: requiresResponse boolean for distinguishing questions from notifications
- 05-01: Self-referential parentMessageId for response threading
- 05-04: In-memory Map for task queue (persistent queue not needed for v1)
- 05-04: Dependency checking via taskRepository.findById status check
- 05-04: Agent name generated from taskId prefix
- 06-01: MergeResult mirrors git MergeResult but adds taskId for coordination context
- 06-01: Events use merge: prefix to distinguish from worktree: events
- 06-02: MessageRepository is optional - conflict messages only sent if configured
- 06-02: In-memory queue same pattern as DispatchManager (no persistence for v1)
- 06-03: getMergeQueueStatus named distinctly from getQueueState (dispatch)
- 06-03: coordinate as top-level CLI command for primary workflow action
- 07-01: In-memory Map for mock agent storage (no database needed)
- 07-01: setTimeout for async completion even with delay=0 (consistent behavior)
- 07-01: Resume always completes successfully (simplifies test scenarios)
- 07-02: DispatchManager requires pre-seeded idle agent before spawning new ones
- 07-02: Fixtures use name-to-ID mapping for dependency resolution
- 07-02: MockWorktreeManager allows custom merge results for conflict testing
- 08-01: Use database agent for merge flow (MockAgentManager in-memory, CoordinationManager needs DB)
- 08-01: Test current behavior: all tasks ready (DispatchManager dependsOn always empty)
- 08-01: Pre-seed idle agent before dispatch (DispatchManager requirement)
- 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
- 08.1-02: MockAgentScenario aligned with agent output schema (status-based discriminated union)
- 08.1-02: TestHarness convenience methods for scenario setup (setAgentDone/Question/Error)
- 08.1-02: getPendingQuestion exposed through TestHarness interface
- 09-02: Database is source of truth for recovery tests (not in-memory queue state)
- 09-02: Blocked task recovery via DB update and re-queue
- 09-02: Q&A flow tests use schema-aligned scenarios
- 10-01: Status 'questions' (plural) for clarity when payload is array
- 10-01: Each question has id field for matching answers in batched resume
- 10-01: Single question uses array: `questions: [{ id: 'q1', question: '...' }]`
- 10-02: Answers passed as Record<string, string> mapping question ID to answer
- 10-02: formatAnswersAsPrompt formats as [id]: answer for Claude resume
- 10-02: CLI accepts JSON object or single string (defaults to q1 key)
- 10-03: setAgentQuestion convenience wraps single question in array format
- 10-03: Multi-question test covers 3 questions with mixed option types
- 11-01: AgentMode stored in database with 'execute' default for backwards compatibility
- 11-01: Discuss mode outputs decisions array with topic/decision/reason structure
- 11-01: Breakdown mode outputs phases array with number/name/description/dependencies
- 11-01: AgentStoppedEvent reason extended with context_complete and breakdown_complete
- 11-03: Mode extracted from spawn options with 'execute' default for backwards compatibility
- 11-03: Separate handler methods per mode (handleExecuteOutput, handleDiscussOutput, handleBreakdownOutput)
- 11-03: Resume uses mode-specific JSON schema for resumed sessions
- 11-04: Repositories optional in tRPC context following existing pattern (agentManager, taskRepository)
- 11-04: createPhasesFromBreakdown accepts pre-numbered phases for Architect breakdown output
- 11-05: Prompts exported from dedicated module for reusability
- 11-05: buildExecutePrompt takes taskDescription, not Initiative (worker agents work on tasks)
- 11-05: Architect procedures validate initiative exists before spawning
- 11-06: Phases command under initiative group (cw initiative phases) for discoverability
- 11-06: Architect commands require --name, optional context/summary flags
- 11-08: TestHarness wired with tRPC caller and initiative/phase repositories
- 11-08: Architect scenario helpers via MockAgentManager (context_complete, breakdown_complete)
- 11-08: E2E tests cover full discuss -> breakdown -> phase persistence workflow
- 12-01: TaskBreakdown includes type field matching database task.type enum
- 12-01: Status 'decompose_complete' mirrors 'breakdown_complete' naming pattern
- 12-01: Dependencies array uses integer task numbers for ordering (same as phases)
- 12-02: getNextNumber uses max() aggregate, returning 1 if no plans exist (same pattern as PhaseRepository)
- 12-03: Task execution order adjusted - Task 3 first since Tasks 1-2 depend on AgentStoppedEvent reason type
- 12-03: handleDecomposeOutput follows exact structure of handleBreakdownOutput for pattern consistency
- 12-04: Extended TaskRepository with createDependency for hexagonal architecture compliance
- 12-04: createTasksFromDecomposition maps task numbers to IDs for dependency creation
- 12-05: buildDecomposePrompt takes Plan and Phase (not Initiative) to provide plan-level context
- 12-05: spawnArchitectDecompose associates with planId (not initiativeId) matching decompose scope
- 12-06: Architect decompose added as subcommand under existing architect group (consistent with discuss/breakdown)
- 12-06: Plan commands follow same pattern as initiative commands for consistency
- 12-08: planRepository added to harness for plan operations in E2E tests
- 12-08: Decompose helpers follow same pattern as architect discuss/breakdown helpers
- 12-08: Agent waiting emits agent:waiting event, not agent:stopped (Q&A flow)
- 13-01: Use structured_output field (not result) when --json-schema is used with Claude CLI
- 13-01: Integration tests skipped by default (REAL_CLAUDE_TESTS=1 to enable)
- 14-01: phase_dependencies table mirrors task_dependencies exactly (same FK patterns, cascade delete)
- 14-01: getDependencies/getDependents return string[] IDs for query efficiency
- 14-02: Phase events follow task event naming pattern (phase:queued, phase:started, etc.)
- 14-02: PhaseBlockedEvent has reason string (not blockedBy array) matching existing convention
- 14-03: PhaseDispatchManager methods use Phase suffix (queuePhase, completePhase) for clarity
- 14-03: QueuedPhase includes initiativeId for context association
- 14-03: PhaseDispatchResult simpler than DispatchResult (no agentId field)
- 14-04: In-memory Map for phaseQueue (same pattern as DefaultDispatchManager)
- 14-04: Dependency checking via phaseRepository.findById for status
- 14-04: Sort ready phases by queuedAt (oldest first, no priority like tasks)
- 14-05: PhaseDispatchManager optional in context following existing pattern
- 14-05: createPhaseDependency validates both phases exist before creating dependency
- 14-05: getPhaseDependencies returns { dependencies: string[] } wrapper for API consistency
- 14-06: Phase commands added as top-level command group (cw phase) following dispatch pattern
- 14-06: Commands use inline definition pattern (same as all other CLI commands in index.ts)
- 14-08: PhaseDispatchManager wired into TestHarness following DispatchManager pattern
- 14-08: E2E tests cover 4 core scenarios: independent, sequential, diamond, blocked
- 16-01: CSS import added to main.tsx (was missing from Task 1, required for Tailwind output)
- 16-01: App.tsx uses cn() from @/lib/utils to verify path alias and Tailwind integration
- 16-02: Shared types package uses rootDir=../.. (no composite) for relative imports into backend
- 16-02: skipLibCheck avoids drizzle-orm third-party declaration errors in shared package
- 16-03: httpBatchLink URL set to /trpc (Vite proxy forwards to backend, same-origin in prod)
- 16-03: QueryClient defaults: refetchOnWindowFocus=false, retry=1
- 16-03: tsconfig project references to shared not needed (npm workspaces symlink handles resolution)
- 16-04: TanStackRouterVite plugin must come BEFORE react plugin in Vite config
- 16-04: Root route wraps all pages with AppLayout via Outlet
- 16-04: / redirects to /initiatives via beforeLoad + throw redirect
- 16-04: Agents/Tasks/Settings nav items disabled spans (out of Phase 16-19 scope)
- 16-04: shadcn CLI creates files in literal @/ dir - manually moved to src/components/ui/
- 16-05: No code changes needed - all scaffold work from 16-01 through 16-04 builds and type-checks cleanly
- 17-01: Use className overrides on stock shadcn Badge (no new variants)
- 17-01: Generic string status prop for StatusBadge (not tied to specific type)
- 17-01: Dashboard components live in packages/web/src/components/ (not ui/)
- 17-02: SerializedInitiative type for tRPC Date→string serialization (wire format differs from DB schema)
- 17-02: Per-card phase stats fetch via trpc.listPhases (N+1 acceptable for v1)
- 17-03: No deleteInitiative tRPC procedure; Delete menu item disabled as placeholder
- 17-03: Controlled dialog pattern: open/onOpenChange props with form reset via useEffect
- 17-03: shadcn CLI @/ dir bug workaround applied again (same as 16-04)
- 17-04: Dashboard page owns create action (Option A) — keeps AppLayout generic for other pages
- 17-04: Route param is $id matching existing $id.tsx file route definition
- 18-01: Reuse SerializedInitiative shape for header props (dates as ISO strings)
- 18-01: Actions button disabled as placeholder — wired in Plan 04
- 18-02: SerializedTask type defined in TaskRow (same Date-to-string serialization pattern as SerializedInitiative)
- 18-02: Phase hierarchy flattened — Plan layer hidden per decision 15-02, tasks rendered directly under phase
- 18-02: Underscore prefix for unused type prop in DependencyIndicator (_type) to satisfy noUnusedParameters
- 18-03: SerializedTask type mirrors SerializedInitiative pattern (Date fields become string over JSON)
- 18-03: Both DecisionList and TaskDetailModal are purely presentational with callback props (no tRPC calls inside)
- 18-04: PhaseWithTasks helper component pattern solves hooks-in-loops problem for nested data fetching
- 18-04: PlanTasksFetcher renders null — data-only component for per-plan task fetching with stable hook count
- 18-04: Task counts aggregated via callback from PhaseWithTasks to page-level state
- 18-04: DecisionList passed empty array — no backend endpoint for decisions yet
- 18-04: Phase/task dependencies simplified (empty arrays) for v1 — full dependency resolution deferred
- 19-01: Re-export PendingQuestions/QuestionItem from agent/types.ts via shared package (rootDir=../.. path)
- 19-01: listWaitingAgents filters agentManager.list() in-memory (agents are in-memory, no DB query needed)
- 19-02: Inline formatRelativeTime helper in MessageCard (no separate utils file per plan spec)
- 19-02: Filter/sort as button groups (not dropdowns) for simplicity per plan spec
- 19-02: Count badge shows total joined entries (not filtered count) to match wireframe "Agent Inbox (3)"
- 19-02: cn() import from @/lib/utils for className merging (consistent with all other components)
- 19-03: OptionGroup value is always string (comma-joined for multi-select) for consistent interface
- 19-03: QuestionForm owns answer state internally via useState (self-contained component)
- 19-03: allowOther defaults to true per plan spec
- 19-04: Detail panel inline in page file (not a separate component) — page-specific layout
- 19-04: useUtils() for query invalidation on mutation success (same pattern as initiative detail)
- 19-04: Serialize agent/message data to string dates for InboxList props (wire format consistency)
- 20-01: Queue + deferred promise pattern for bridging push (EventBus) to pull (async generator)
- 20-01: tracked() wrapper on each event for client-side reconnection via lastEventId
- 20-01: Fallback AbortSignal (new AbortController().signal) when opts.signal is undefined
- 20-01: Vite proxy works for SSE without changes (http-proxy streams chunked responses by default)
- 20-02: httpSubscriptionLink (stable export) over unstable_ prefix — both available in @trpc/client v11
- 20-02: Subscription-driven invalidation (not local state) — simplest approach, reuses existing React Query cache
- 20-02: Silent onError callbacks — pages degrade to manual refresh when backend is not running
- 20-02: No new packages needed — splitLink and httpSubscriptionLink ship with @trpc/client v11
- 21-01: ErrorBoundary wraps Outlet only (not entire AppLayout) so nav shell survives render errors
- 21-01: Toaster outside AppLayout as sibling — available even if layout breaks
- 21-01: notFoundComponent uses shadcn Button with asChild + Link (consistent with component library)
- 21-01: One success and one error toast per mutation — no toasts for query failures (those have inline error states)
- 21-02: Skeleton component in components/ (not ui/) — app-specific, not a shadcn primitive
- 21-02: Inbox skeleton lives in inbox.tsx route (not InboxList component) since InboxList receives pre-loaded data
- 21-03: Removed disabled nav stubs (Agents, Tasks, Settings) — stubs create false promises for v2.0
- 21-03: TaskRow agent names link to /inbox — simplest cross-screen navigation for agent context
- 21-03: Inbox task links go to /initiatives — no direct task-to-initiative mapping on frontend
- 21-03: Mobile drill-down pattern hides list on mobile when detail selected, shows back button
- 21-04: Fixed toast ID 'sub-error' prevents duplicate notifications across concurrent subscription failures
- 21-04: duration: Infinity keeps error toast visible until user dismisses — persistent connection feedback
- 21-04: No reconnection logic — tRPC SSE httpSubscriptionLink handles reconnection via EventSource retry
- 21-04: SpawnArchitectDropdown already covered by 21-01 — verification task was no-op
- 21-05: autoCodeSplitting: true on TanStackRouterVite plugin — automatic route splitting without manual .lazy.tsx files
- 21-05: PlanTasksFetcher onTasks moved to useEffect to prevent setState-during-render loops

### Pending Todos

None yet.

### Roadmap Evolution

- Phase 1.1 inserted after Phase 1: Hexagonal architecture with events, tests, and tRPC (URGENT)
  - Retrofits Phase 1 code before continuing to Phase 2
  - Establishes architectural foundation for rest of project
- Milestone v1.1 created: Test infrastructure, 3 phases (Phase 7-9)
- Milestone v1.2 created: Architect & Multi-Question, 4 phases (Phase 10-13)
- Milestone v1.3 created: Parallel Execution & UI Design, 2 phases (Phase 14-15)
- Milestone v2.0 created: Frontend, 6 phases (Phase 16-21)

### Blockers/Concerns

None.

## Session Continuity

Last session: 2026-02-05
Stopped at: Completed 21-05 (Code Splitting & Data-Fetching Performance)
Resume file: None