cogniflow: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Planning Documents

Always read these before starting implementation work:

• REQUIREMENTS.md — functional and non-functional requirements; the authoritative source for what the system must do
• ARCHITECTURE.md — package structure, core Go interfaces, MySQL schema, REST API contract, CEL usage, gRPC plugin protocol, and Docker Compose setup
• PROJECT_PLAN.md — milestones M1–M15 with deliverables and testable criteria; use this to understand what has been built and what comes next
• REQUIREMENTS_EVAL.md — requirements for the workflow evaluation / quality-testing feature
• ARCHITECTURE_EVAL.md — architecture for the eval subsystem (graders, eval runner, grader plugins)
• PROJECT_PLAN_EVAL.md — milestones ME1–ME5 for the eval feature

The memory file milestone-status.md (in the project memory directory) tracks which milestones are complete. Update it whenever a milestone is finished.

---

Definition of Done

A milestone is not complete until all of the following pass from backend/:

1. go build ./... — no compile errors
2. go test ./... — all tests pass, coverage >80% on new packages
3. golangci-lint run ./... — zero warnings (default linter set)

Run these in order before marking a milestone done or committing final work.

---

Commands

All Go commands must be run from backend/ (the Go module root). All frontend commands run from frontend/.

# Backend
cd backend
go build ./...                         # compile check
go build -o bin/server ./cmd/server    # build binary
go run ./cmd/server                    # run locally (requires DB_DSN env var)
go test ./...                          # all tests
go test ./internal/engine/...          # single package
go test -run TestCycleDetect ./internal/engine/...  # single test
golangci-lint run ./...                # lint (must be zero warnings before milestone complete)

# Frontend (once scaffolded)
cd frontend
npm install
npm run dev     # Vite dev server
npm run build   # production bundle
npm run lint