darq: Instructions file for Claude Code

CLAUDE.md

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

Project

darq is a Rust CLI + TUI that orchestrates spec-to-app software generation through an autonomous pipeline. It takes a GitHub issue, plans implementation via ACP-compatible AI agents, validates output through SAT (Scenario-driven AI Testing) with persona-based scoring, and feeds results back into a learning loop. Core loop: spec → plan → implement → review → merge → test → learn → repeat.

Build & Test Commands

cargo build                          # Build all crates (debug)
cargo build --release                # Release build
cargo test                           # All unit tests (both crates)
cargo test -p darq-core              # Core library tests only
cargo test -p darq                   # CLI binary tests only
cargo test test_workflow_registry    # Single test by name
cargo test -p darq-core workflow::   # Tests in a module
cargo clippy --workspace             # Lint
cargo fmt --check                    # Format check

Integration tests live in tests/ at the workspace root:

cargo test --test spine_integration
cargo test --test sweep_integration
cargo test --test workflow_integration

The binary and package are both named darq:

cargo run -- sat run --target /path/to/project
cargo run -- run issue 42 --full

Workspace Structure

Two-crate workspace:

• crates/darq-core — All logic. Library crate. Uses thiserror for typed errors.
• crates/darq — Thin binary wrapper (package name darq). Uses anyhow for error context. Never use anyhow in darq-core.

Architecture

Daemon Model

darq uses a daemon architecture. Most CLI commands are thin clients that connect to a background daemon via Unix socket (~/.darq/daemon.sock).

• darq daemon start launches the daemon (owns DB, event broadcaster, workflow engine)
• CLI commands auto-start the daemon if not running (DaemonClient::connect_or_start)
• JSON-lines protocol over Unix socket for IPC
• darq tui connects to the daemon for real-time event streaming