clarity-agent: Instructions file for Codex

Clarity Agent Guidelines

Commands

# Install all dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run a single test file
uv run pytest tests/test_packet_status.py

# Run a single test by name
uv run pytest tests/test_packet_status.py::TestPacketStatus::test_something

# Lint
uv run ruff check .

# Type check
uv run pyright

# Run the web UI (headless, against a project dir)
uv run python clarity.py web /tmp/test-project

# Run the CLI
uv run python clarity.py cli /tmp/test-project

# Run the desktop app
uv run python clarity.py app

# List the models the configured provider offers
uv run python clarity.py models
uv run python clarity.py models --debug   # explain how credentials resolved

# Rebuild the React frontend (only when changing web/ source)
cd web && npm install && npm run build

# Frontend dev server with hot-reloading (proxies /api and /ws to :8420)
# Terminal 1: uv run python clarity.py web /tmp/test-project
# Terminal 2: cd web && npm run dev

Architecture

Mental model: process guides are the program; Python is the stdlib

processes/ contains markdown files that act as the control flow — an LLM reads and executes them. src/clarity_agent/ contains Python infrastructure those processes call. clarity.py is the entry point.

Entry point and routing

processes/clarity-agent.md is "main". It checks whether .clarity-protocol/ exists, runs packet_status.py to assess state, and routes to the correct process guide. After any process completes, control returns here.

src/clarity_agent/protocol/packet_status.py is the build system / flow controller. It maintains a SHA-256 dependency graph among protocol documents (stored in config.json) and detects when a dependency has changed since a document was last accepted. The first stale document in topological order is what to work on next. The --agent flag produces markdown suitable for injection into an AI system prompt.

Document dependency graph

problem → stakeholders → requirements → open-questions → solution → failures
                                                                  → architecture (↔ failures)
                                                                  → solution-summary (← solution + architecture)