xchecker: Instructions file for Codex

CLAUDE.md

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

Project Overview

xchecker is a Rust CLI tool for orchestrating spec generation workflows using LLMs. It transforms rough feature ideas into structured requirements, designs, and implementation tasks through a multi-phase pipeline.

Workspace Layout

xchecker is a Cargo workspace with a stable facade in the root crate:

• crates/xchecker-utils: foundations (paths/sandbox, atomic write, logging, redaction, runner, types)
• crates/xchecker-config: config model + discovery + validation + builder + selectors
• crates/xchecker-llm: provider backends (claude-cli, gemini-cli, openrouter, anthropic)
• crates/xchecker-engine: orchestration + phases + packet + fixup + receipt + status + workspace + gate + hooks
• src/lib.rs + src/main.rs: stable API re-exports and CLI entrypoint for xchecker

Build & Test Commands

# Build
cargo build                    # Debug build
cargo build --release          # Release build

# Run all tests (fast)
cargo test --workspace --lib --bins

# Run local-green tests (no external dependencies)
cargo test --workspace --lib && cargo test --workspace --tests -- --skip requires_claude_stub --skip requires_real_claude --skip requires_xchecker_binary

# Run tests with claude-stub (requires building stub first)
cargo build --bin claude-stub --features dev-tools
cargo test --workspace --tests -- --include-ignored --skip requires_real_claude

# Run a single test
cargo test test_name -- --nocapture

# Linting and formatting
cargo fmt -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Run benchmarks
cargo bench

# Documentation validation
cargo test --features dev-tools --test doc_validation -- --test-threads=1

Architecture

Phase Pipeline

xchecker executes specs through a sequential phase pipeline:

Requirements -> Design -> Tasks -> Review -> Fixup -> Final

Each phase:

1. Builds a packet (context gathered from artifacts)
2. Scans for secrets (blocks execution if detected)
3. Invokes LLM (Claude CLI, Gemini CLI, HTTP providers, or dry-run simulation)
4. Postprocesses response into artifacts
5. Writes artifacts atomically via .partial/ staging
6. Generates receipts with BLAKE3 hashes