# CLAUDE.md — Agent Guidelines for Veritas Kanban

This file defines project-specific rules, context, and lessons learned for AI agents working on Veritas Kanban. Update it after every mistake, discovery, or workflow change.

> **Last updated:** 2026-02-06 (v2.0.0)  
> **Freshness check:** Review monthly or after major releases

---

## Project Context

**Veritas Kanban** is an open-source AI-native task management system. It's designed for humans + AI agents to collaborate on work through a shared board, CLI, and API.

- **Primary language:** TypeScript (strict mode)
- **Monorepo:** pnpm workspaces — `server/`, `web/`, `cli/`, `shared/`, `mcp/`
- **Build:** Node 22+, pnpm 9+
- **Test:** Vitest (server), React Testing Library (web)
- **Style:** ESLint + Prettier, conventional commits

---

## Architecture Rules

### Server (Express + TypeScript)

- All routes go through centralized middleware in `server/src/middleware/`
- Auth: JWT + API keys, localhost bypass for dev (`VERITAS_AUTH_LOCALHOST_BYPASS=true`)
- Storage: Abstract via `storage/interfaces.ts` — never import `fs` directly in services
- Error handling: Use `UnauthorizedError`, `ForbiddenError`, `BadRequestError`, `InternalError`
- Pagination: Use `sendPaginated(res, items, {page, limit, total})`

### Web (React + Vite)

- State: Zustand stores, no prop drilling past 2 levels
- Realtime: WebSocket via `useRealtimeUpdates` hooks
- Styling: Tailwind CSS, component-scoped styles

### CLI (Commander.js)

- Every command mirrors an API endpoint
- JSON output via `--json` flag for scripting
- Use `chalk` for colored output

---

## Code Quality Gates

1. **Cross-model review required for all code changes**
   - If Claude writes it, GPT reviews (and vice versa)
   - See `prompt-registry/cross-model-review.md`

2. **No hardcoded secrets** — use environment variables

3. **All user input validated** — use Zod schemas

4. **Path traversal prevention** — use `validatePathSegment()` from security module

5. **Tests for new features** — aim for >80% coverage on critical paths

---

## Common Mistakes (Don't Repeat These)

### Security

- ❌ Forgot global middleware — flagged missing per-route auth that was already in `app.use()`
- ❌ Used `path.join()` without validation — allows `../` traversal
- ✅ Always check `validatePathSegment()` for any user-supplied path component

### Architecture

- ❌ Imported `fs` directly in service files — breaks storage abstraction
- ❌ Added polling when WebSocket hook existed — use `useRealtimeAgentStatus`
- ❌ Frontend interface didn't match server response (e.g., `totalAgents` vs `total` in registry stats)
- ✅ Check for existing hooks/services before creating new ones
- ✅ Server response format is source of truth — frontend interfaces must match exactly

### Multi-Agent (v2.0)

- Agent names use ALL CAPS for acronyms (VERITAS, TARS, CASE, K-2SO, R2-D2, MAX)
- Agent registry is file-based at `.veritas-kanban/agent-registry.json`
- Heartbeat timeout: 5 min (configurable). Stale check interval: 1 min
- Activity data uses `status-history` (not `activity.json`) as source of truth
- Timezone: server uses local time; clients send `?tz=<offset>` for cross-region display
- Dashboard widgets: use `onMutate` for optimistic updates (archive, status changes)

### Testing

- ❌ Used wrong field in backfilled events (`status: "success"` vs `success: true`)
- ✅ Match actual runtime schema exactly in test fixtures

---

## Conventions

### Naming

- Files: `kebab-case.ts`
- Components: `PascalCase.tsx`
- Variables/functions: `camelCase`
- Constants: `UPPER_SNAKE_CASE`

### Git

- Branch: `feat/description-issue-number`, `fix/description-issue-number`
- Commit: Conventional commits (`feat:`, `fix:`, `docs:`, `chore:`)
- PR: Always reference issue number

### Task Workflow

1. Start timer: `vk begin <id>`
2. Update status: `vk status <id> in-progress`
3. Work, commit, push
4. Cross-model review
5. Complete: `vk done <id> "summary"`

---

## File Locations

| What             | Where                                 |
| ---------------- | ------------------------------------- |
| API routes       | `server/src/routes/`                  |
| Services         | `server/src/services/`                |
| Schemas          | `server/src/schemas/`                 |
| Storage          | `server/src/storage/`                 |
| React components | `web/src/components/`                 |
| Zustand stores   | `web/src/stores/`                     |
| CLI commands     | `cli/src/commands/`                   |
| Shared types     | `shared/src/`                         |
| MCP server       | `mcp/src/`                            |
| Prompts          | `prompt-registry/`                    |
| SOPs             | `docs/SOP-*.md`                       |
| Agent registry   | `.veritas-kanban/agent-registry.json` |
| Telemetry events | `.veritas-kanban/telemetry/`          |

---

## When to Update This File

- After a bug that could have been prevented by a rule
- After discovering a pattern that should be standard
- After a cross-model review catches something systemic
- Monthly freshness review (add to calendar)

---

## Credit

Structure inspired by Anthropic's CLAUDE.md convention and [BoardKit Orchestrator](https://github.com/BoardKit/orchestrator) by Monika Voutov.
