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: 18 of 21 (Initiative Detail) Plan: 2 of 4 in current phase Status: In progress Last activity: 2026-02-04 - Completed 18-02-PLAN.md

Progress: █████████░ 97%

Performance Metrics

Velocity:

• Total plans completed: 67
• Average duration: 3 min
• Total execution time: 188 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

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-04 Stopped at: Completed 18-02-PLAN.md Resume file: None