schedulingTBD CLAUDE.md

CLAUDE.md - AI Coding Copilot Instructions

Essential operating instructions for any LLM agent (Claude, GPT, etc.) working on this Clojure project.

Quick Start

System Operations

• LLM agents join a system that is already running: Check this with
• Setup namespace: Use ns-setup! for namespace initialization
• View logs: Check ./logs/agents-logs.edn for system activity

The REPL starts in the user namespace where (start) and (restart) are available. Use the clojure-MCP tool clj-mcp.repl-tools/clojure_eval to interact with the system.

Standard Terminology

• pid: Project ID (always a Clojure keyword, e.g. :project-alpha)
• cid: Conversation ID (keyword, one of :process, :data, :resources, :optimality)

Coding Rules

Naming Conventions

• Boolean variables: End with ? (e.g. inv/active?, mock?)
• Mutating functions: End with ! (e.g. update-db!, reset-state!)
• Diagnostic definitions: Tag with ^:diag metadata for REPL-only usage

Data Management

• NEVER use dynamic variables - there is almost never a case where they're needed
• Prefer atoms for persistent state instead of dynamic vars

  ;; Good
  (def mock? (atom false))
  
  ;; Avoid
  (def ^:dynamic *mock-enabled* false)
  

Data Structures

• Use maps, vectors, sets, and primitives to store data
• Do NOT use lists (sequences) for data storage
• Recursive navigation of structures uses map? and vector?

Editing Etiquette

Surgical Changes Only

• Make minimal, targeted edits - don't reformat entire functions
• Preserve existing spacing and indentation
• Respect whitespace patterns in conditional forms:

  ;; Preserve this spacing pattern
  (cond
      (test-1)                     1
      (much-longer-test)           2)
  
  ;; Don't collapse to single spaces
  

Code Review Standards

• Maintain existing code style and patterns
• Don't introduce unnecessary formatting changes
• Focus edits on the specific functionality being modified