Skip to content

AGENTS.md

Latest commit

 

History

History
49 lines (40 loc) · 3.13 KB

AGENTS.md

File metadata and controls

49 lines (40 loc) · 3.13 KB

Repository Guidelines

Project Structure and Module Organization

  • src/ holds the Rust library and CLI code; src/main.rs wires the CLI and i18n.
  • src/x/ contains experimental integrations (cursor, claude_code, codex).
  • src/tool/ contains developer utilities used by the CLI.
  • tests/ contains integration tests; files are named *_tests.rs.
  • templates/ stores prompt templates; locales/ stores i18n YAML files.
  • artifacts/testing_config_home/ is the test fixture config root used by dev commands.
  • scripts/ has helper scripts; docs/ has design and planning notes.

Build, Test, and Development Commands

This project targets Rust edition 2024 and uses the nightly toolchain.

  • just build / just build-release: debug or release builds.
  • just run -- <args>: run with test config (LLMAN_CONFIG_DIR=./artifacts/testing_config_home).
  • just run-prod -- <args>: run with production config.
  • just test: run the full test suite.
  • just check: format check, lint, and tests.
  • just check-all: check plus docs, release build, and SDD template checks.
  • just check-sdd-templates: verify SDD template version headers and locale parity.
  • just fmt / just lint: rustfmt and clippy.

Cargo equivalents use cargo +nightly ....

Coding Style and Naming Conventions

  • Use rustfmt defaults (4-space indentation) and keep code warning-free; clippy runs with -D warnings.
  • Use snake_case for file and module names; keep CLI subcommands lowercase with hyphens for multi-word names.
  • Prefer small, focused functions and reuse shared helpers in src/path_utils.rs and src/config.rs.

Testing Guidelines

  • Add unit tests near the code when possible, and integration tests under tests/.
  • Name new integration test files *_tests.rs and keep test names descriptive.
  • Interactive CLI flows (e.g. inquire prompts) do not require automated tests; test the core, non-interactive logic instead.
  • Use LLMAN_CONFIG_DIR=./artifacts/testing_config_home to avoid touching real user config.
  • Avoid workspace pollution: tests that may create files/dirs MUST use tempfile::TempDir (or TestEnvironment) and write only inside it so everything is auto-cleaned.
  • Avoid parallel test collisions: don’t use fixed relative paths/identifiers in the repo root (e.g. config, config.yaml); prefer unique temp paths and guard env/cwd changes with crate::test_utils::TestProcess.
  • When editing templates/sdd/**, run just check-sdd-templates (also in just check-all).

Commit and Pull Request Guidelines

  • Commit messages use a short type prefix such as feat:, fix:, refactor:, doc:, or bump: with an optional scope, for example fix(security): ....
  • Keep commits focused and in present tense.
  • PRs should include a clear summary, testing commands run, and links to related issues. Include sample CLI output when user-visible behavior changes.

Configuration Notes

  • Default config lives in ~/.config/llman/ unless overridden by LLMAN_CONFIG_DIR.
  • LLMAN_LANG is reserved; only en is supported unless explicitly requested otherwise.
  • i18n strings are placeholders; English-only is required unless explicitly requested otherwise.