agentcmd: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code when working with this repository.

Documentation Map

CLAUDE.md Files

• Root (this file) - Monorepo essentials + critical rules
• apps/app/CLAUDE.md - Full-stack app integration
• apps/app/src/client/CLAUDE.md - Frontend patterns
• packages/agent-cli-sdk/CLAUDE.md - AI CLI SDK
• packages/agentcmd-workflows/CLAUDE.md - Workflow SDK

.agent/docs/ Reference Guides

• backend-patterns.md - Domain services, routes, error handling
• frontend-patterns.md - React patterns, state management
• workflow-system.md - Workflow engine, Inngest integration
• websocket-architecture.md - WebSocket patterns, EventBus
• database-guide.md - Prisma patterns, migrations
• troubleshooting.md - Common issues and solutions
• deployment.md - Build, deploy, production
• architecture-decisions.md - Why we chose these technologies
• testing-best-practices.md - Testing patterns
• branding.md - Project identity, design system

Project Overview

Turborepo monorepo for AI agent workflow tools:

• apps/app: Full-stack application (React + Vite frontend, Fastify backend)
• apps/appsite: Marketing site (Next.js)
• packages/agent-cli-sdk: TypeScript SDK for AI CLI orchestration
• packages/agentcmd-workflows: Workflow utilities library

Tech Stack:

• Frontend: React 19, Vite, TanStack Query, Zustand, Tailwind v4
• Backend: Fastify, Prisma (SQLite), Inngest, WebSocket
• Build: Turborepo, pnpm, TypeScript 5.9

Critical Rules

Import Conventions

✅ DO - No file extensions, @/ aliases only:

import { foo } from "./bar";
import { getProjectById } from "@/server/domain/project/services/getProjectById";

❌ DON'T - File extensions, relative paths:

import { foo } from "./bar.js";
import { getProjectById } from "../../../domain/project/services/getProjectById";

✅ DO - Top-level imports:

import type { PhaseDefinition } from "agentcmd-workflows";