decompose: Instructions file for Codex

AGENTS.md

Guidance for agents (human or automated) contributing to decompose.

Project overview

decompose is a Rust process orchestrator for local development. See README.md for the pitch and CLAUDE.md for design notes.

Repo structure

src/
  main.rs      Entry point; calls run_cli()
  lib.rs       CLI command handlers, log streaming
  cli.rs       Clap argument definitions
  config.rs    YAML parsing, merging, .env loading, variable interpolation
  daemon.rs    Daemon lifecycle, supervisor loop, IPC handlers
  model.rs     Core types (ProcessStatus, HealthProbe, etc.)
  ipc.rs       Request/Response protocol, socket helpers
  output.rs    JSON/table output formatting
  paths.rs     XDG path management, instance ID generation

tests/         Integration tests (spawn the binary end-to-end)
examples/      Sample compose files
assets/        Logo and static assets
.github/       CI and release workflows
flake.nix      Nix dev shell + package

Build, test, lint

All commands are expected to pass locally and in CI:

cargo build --locked --all-targets
cargo test --locked --all-targets
cargo fmt --all -- --check
cargo clippy --locked --all-targets -- -D warnings
cargo doc --locked --no-deps

Use nix develop to get a toolchain-pinned shell if you prefer.

For book changes, run mdbook build docs/ (CI uses mdBook 0.5.4), then python3 scripts/check-docs.py after building the binary. The checker validates local HTML links and anchors, then runs the quickstart and migration examples extracted from docs/src, plus the documented multiple-file invocation. It needs Python 3, a POSIX shell, and permission to bind local sockets. It uses temporary HOME/XDG directories and unused ports, and shuts down its daemons on failure. Keep these selected examples runnable; the checker deliberately does not execute arbitrary shell blocks elsewhere in the book.

After changing Cargo.lock (including a package version bump), Cargo.toml, flake.lock, or the vendoring derivation, verify the Nix vendor hash: