lxcafe/.agents/AGENTS.md

AGENTS

I created this AGENTS.md to help agentic coding assistants work in this repository. It contains

1. Build / lint / test commands (including how to run a single test) and
2. Code style guidelines and conventions to follow when editing code here.

Repository state

• This repository contains shell scripts for Linux Mint XFCE post-installation setup.
• Main scripts are located in post_installation_script/ directory.
• Testing infrastructure is in post_installation_script_test/ (Docker/Podman test containers).
• No build system, package.json, Makefile, or language-specific project files were detected.
• There are no Cursor rules or Copilot instruction files in the repo (checked paths below).
  • .cursor/rules/ : not found
  • .cursorrules : not found
  • .github/copilot-instructions.md : not found

If you add new code (Go, Python, Node, Rust, Java, etc.), follow the per-ecosystem quick commands below.

1. Build / Lint / Test commands

• General notes

  • Run commands from the repository root unless a submodule or service has its own README.
  • Prefer local, repo-scoped toolchains (venv, node_modules/.bin, go modules, cargo) to avoid global state.

• Shell scripts

  • Quick check: shellcheck scripts/*.sh (install shellcheck first).
  • Run an individual script: bash path/to/script.sh or ./script.sh (ensure executable bit set).
  • Syntax check: bash -n path/to/script.sh
  • Trace execution: bash -x path/to/script.sh (shows each command as it runs)

• Testing shell scripts

  • See post_installation_script_test/README.md for detailed container-based testing instructions.
  • Quick start:
    • Build image: ./post_installation_script_test/01_create_image.sh
    • Start container: ./post_installation_script_test/02_start_container_with_image.sh

• Python (if added)

  • Install: python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
  • Lint: ruff . or flake8 .
  • Format: black .
  • Test all: pytest -q
  • Run a single test: pytest path/to/test_file.py::TestClass::test_method -q

• Node / JavaScript / TypeScript (if added)

  • Install: npm ci or pnpm install / yarn install
  • Lint: npm run lint (or npx eslint .)
  • Format: npx prettier --write .
  • Test all: npm test (or npx vitest / npx jest)
  • Run a single test:
    • Jest: npx jest path/to/file.test.js -t "test name regex"
    • Vitest: npx vitest run path/to/file.spec.ts -t "test name"

• Go (if added)

  • Build: go build ./...
  • Lint: golangci-lint run (if configured)
  • Test all: go test ./...
  • Run a single test: go test ./pkg/name -run TestFunctionName

• Rust (if added)

  • Build: cargo build
  • Lint: cargo clippy
  • Test all: cargo test
  • Run a single test: cargo test test_name -- --exact

• Java / Maven (if added)

  • Build: mvn -DskipTests package
  • Lint/format: use spotless/checkstyle if configured
  • Test all: mvn test
  • Run a single test: mvn -Dtest=ClassName#methodName test

• .NET (if added)

  • Build: dotnet build
  • Test all: dotnet test
  • Run a single test: dotnet test --filter FullyQualifiedName~Namespace.ClassName.MethodName

• CI / Automation

  • If you add GitHub Actions, keep workflows idempotent and cache dependencies carefully.
  • Avoid secrets in workflows; read sensitive values from repository/organization secrets.

2. Code style guidelines

The guidance below is intentionally general and focuses on consistency, readability and safety so agentic tools can make changes predictably across multiple languages.

• Formatting

  • Use an automated formatter for the language (Black for Python, Prettier for JS/TS, gofmt/gofmt -s for Go, rustfmt for Rust). Commit formatted code only.
  • Use an editorconfig file for basic whitespace/indentation rules when possible.

• Imports / dependencies

  • Keep imports explicit and minimal: import only what you use.
  • Group imports in a logical order (language default + third-party + local project). Leave a blank line between groups.
  • Don’t commit unused dependencies; remove them from lock files / manifests and run the linter.

• Types / typing

  • Prefer explicit types where the language supports them (TypeScript types, Python type hints, Go static types).
  • Add types for public interfaces and complex logic; internal simple helper functions may rely on inference.

• Naming conventions

  • Use clear, descriptive names. Prefer calculate_total, prepare_connection, user_id style for snake_case languages.
  • For camelCase languages (JS/TS): calculateTotal, prepareConnection.
  • Types and classes: use PascalCase/UpperCamelCase: UserService, HttpClient.
  • Constants: use UPPER_SNAKE_CASE or language-specific constant conventions.

• Functions and modules

  • Keep functions small (ideally < 40 lines) and single-responsibility.
  • Prefer pure functions where possible; keep side effects explicit and isolated.
  • Organize modules by feature/domain, not solely by type (avoid monolithic god-modules).

• Error handling

  • Fail fast and return/raise errors with context (message + cause) rather than swallowing them.
  • Avoid logging raw errors in library code; return errors to callers and let the application layer decide logging.
  • Use typed error types when the language supports it (Go error types, custom exceptions in Python/JS).
  • Clean up resources with finally/defer equivalents to avoid leaks.

• Tests

  • Prefer small, deterministic unit tests. Mock external IO and network where reasonable.
  • Use explicit fixtures and avoid implicit global state between tests.
  • Name tests with the behavior they assert: test_calculate_total_with_discounts or shouldReturn400WhenMissingField.

• Logging and observability

  • Use structured logging where available (JSON structured logs for services).
  • Avoid printing raw stack traces to stdout in production code; include them at debug level.

• Security and secrets

  • Never commit secrets, API keys, or credentials. Use environment variables and vaults.
  • Validate and sanitize external input at the boundaries of the system.

• Performance

  • Measure before optimizing. Prefer clarity over micro-optimizations unless a hotspot is identified.

3. Code review / commit guidance for agents

• Make small, focused commits and include a one-line summary plus a short description of the why.
• When changing behavior, add or update tests that verify the new/changed behavior.
• If you reformat files automatically, include the formatter command in the commit message to make CI reproduction easy.

4. Repo housekeeping checks (recommended for agents)

• When adding a new language or framework, add an entry to this file with the exact commands required to build/test.
• Add CI workflows to run lint + tests on PRs and enable branch protection rules if this becomes a shared repo.
• Session storage: Store session logs and working notes in .agents/sessions/ folder for future reference. Use descriptive filenames (e.g., session-<date>-<topic>.md).

5. Cursor / Copilot rules

• Cursor rules: none present at .cursor/rules/ or .cursorrules in this repository.
• GitHub Copilot instructions: none present at .github/copilot-instructions.md.

If you add any of these files, update this document and include the exact file path and relevant sections for agents to follow.

Quick checklist for an agent making changes

• Run local linter/formatter configured for the language before opening a PR.
• Run the test suite and the single-test command for any tests you added/changed.
• Do not add secrets to the tree; use placeholders and document required environment variables.

Next steps (recommended)

1. Add a minimal Makefile or package.json scripts for common tasks so agents can run make test / npm test.
2. If the project will contain multiple services, add per-service README files and CI workflows.
3. Add EditorConfig + language-specific formatter configs (pyproject.toml, .prettierrc, rustfmt.toml) to lock formatting rules.

Files referenced

• Root README.md
• post_installation_script/README.md - main script usage
• post_installation_script_test/README.md - testing instructions
• .cursor/rules/ (not present)
• .cursorrules (not present)
• .github/copilot-instructions.md (not present)

If anything in this file needs to be stricter or you want another style (for example a fully opinionated TS style), say which language or style and I will update AGENTS.md accordingly.