Codewalkers/CLAUDE.md

Codewalkers

Multi-agent workspace for orchestrating multiple AI coding agents working in parallel on a shared codebase.

Architecture: docs/architecture.md — system diagram, module map, entity relationships, tech stack.

Quick Reference

Module	Docs	Path
Agent (lifecycle, providers, accounts)	docs/agent.md	apps/server/agent/
Database (schema, repositories)	docs/database.md	apps/server/db/
Server & API (tRPC procedures)	docs/server-api.md	apps/server/server/, apps/server/trpc/, apps/server/coordination/
Frontend (React UI)	docs/frontend.md	apps/web/
CLI & Config	docs/cli-config.md	apps/server/cli/, apps/server/config/
Dispatch & Events	docs/dispatch-events.md	apps/server/dispatch/, apps/server/events/
Git, Process, Logging	docs/git-process-logging.md	apps/server/git/, apps/server/process/, apps/server/logger/, apps/server/logging/
Preview (Docker deployments)	docs/preview.md	apps/server/preview/
Testing	docs/testing.md	apps/server/test/
Database Migrations	docs/database-migrations.md	drizzle/
Logging Guide	docs/logging.md	apps/server/logger/

Pre-implementation design docs are archived in docs/archive/.

Key Rules

• Database migrations: Hand-write SQL in apps/server/drizzle/NNNN_name.sql AND register it in apps/server/drizzle/meta/_journal.json (increment idx, set tag to filename without .sql). Both files must be committed together. Do NOT use drizzle-kit generate — snapshots are stale since migration 0008. See docs/database-migrations.md.
• Logging: Use createModuleLogger() from apps/server/logger/index.ts. Keep console.log for CLI user-facing output only.
• Hexagonal architecture: Repository ports in apps/server/db/repositories/*.ts, Drizzle adapters in apps/server/db/repositories/drizzle/*.ts. All re-exported from apps/server/db/index.ts.
• tRPC context: Optional repos accessed via require*Repository() helpers in apps/server/trpc/routers/_helpers.ts.

UI Patterns

• Shift+click to skip confirmation: Destructive actions (delete task, etc.) show a window.confirm() dialog on click. Holding Shift bypasses the dialog and executes immediately. Apply this pattern to all new destructive buttons.

Build

npm run build && npm link

Run after any change to server-side code (apps/server/**).

Testing

npm test                                                                         # Unit + E2E tests (no API cost)
CW_CASSETTE_RECORD=1 npm test -- <test-file>                                    # Record new cassettes locally
REAL_CLAUDE_TESTS=1 npm test -- apps/server/test/integration/real-providers/ --test-timeout=300000  # Real provider tests (~$0.50)

# Record full-flow cassettes (one-time, costs ~$2–5 in API credits):
CW_CASSETTE_RECORD=1 npm test -- apps/server/test/integration/full-flow/full-flow-cassette.test.ts --test-timeout=3600000
# Commit the generated apps/server/test/cassettes/<hash>.json files afterward.
# Subsequent runs replay from cassettes at no cost: npm test

See docs/testing.md for details, including the cassette system for pipeline integration tests that run without API costs.

Documentation Maintenance

After every code change, update the relevant docs/ file. Documentation must stay in sync with implementation. When adding a new module, table, tRPC procedure, component, or CLI command, update the corresponding doc. When refactoring, update affected docs and remove stale information.

Committing

After completing & verifying changes always commit the changes.