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: 3 of 6 in current phase Status: Completed 21-03 (Cross-Screen Navigation & Mobile Responsive) Last activity: 2026-02-05 - Completed 21-03-PLAN.md (navigation links + mobile responsive)

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

Performance Metrics

Velocity:

Total plans completed: 72
Average duration: 3 min
Total execution time: 204 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-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

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-03 (Cross-Screen Navigation & Mobile Responsive) Resume file: None

18 KiB Raw Blame History