# CLAUDE.md

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

## What Is Loom

Multi-agent project orchestration system. PostgreSQL is the source of truth, Redis is a cache and event bus, FastMCP server provides Claude Code integration. Distributed via `pipx install loom-agents`.

## Commands

```bash
uv sync                          # Install dependencies
uv run pytest tests/ -v          # Run all tests (needs Docker for testcontainers)
uv run pytest tests/integration/test_e2e.py::test_full_agent_workflow -v  # Single test
uv run python -m loom.mcp        # Run MCP server directly (stdio transport)
uv run loom init                 # Scaffold a project
uv run loom up                   # Start Postgres + Redis, run migrations
uv run loom down                 # Stop containers
uv run loom status               # Project overview
```

Tests require Docker Desktop running — testcontainers spins up real Postgres 16 + Redis 7 containers automatically.

## Module Contracts (enforced, not optional)

| Module | Rule |
|--------|------|
| `graph/store.py` | **ONLY** writer to Postgres for task data |
| `graph/cache.py` | **ONLY** reader from Redis for task data; falls back to store.py |
| `bus/channels.py` | **ALL** Redis key patterns; no string literals like `"loom:tasks:ready"` elsewhere |
| `mcp/tools.py` | Each tool **≤15 lines**; thin coordinators only, business logic in graph/ or bus/ |
| `db/migrations/` | **Never** modify existing migration files; always add new numbered files |

## Deep Context

Architecture details, design decisions, phase history, module inventories, workflow patterns, and user preferences are stored in **Weft** (persistent agent memory). Use `weft_prime` at session start or `weft_recall` for specific topics rather than repeating it here.
