CISS.debian.live.builder/AGENTS.md

AGENTS.md

Purpose

This repository builds and maintains the CISS Debian Live Builder for Debian 13 Trixie. Treat every change as security-sensitive and boot-chain-sensitive.

Persistent coding details live in docs/CODING_CONVENTION.md. Review-only instructions live in code_review.md.

Instruction precedence for this repository

Use this order when instructions differ:

1. The current user task prompt defines the immediate objective and task-specific acceptance criteria.
2. This AGENTS.md defines repository-wide constraints and routing guidance.
3. docs/CODING_CONVENTION.md defines detailed coding conventions.
4. code_review.md applies when performing a review or final self-review.
5. Personal/global Codex instructions apply only where they do not conflict with repository rules.

When in doubt, choose the safer, smaller, more easily reviewable change and explain the uncertainty.

Non-negotiable constraints

• Target Debian 13 Trixie unless the task explicitly states otherwise.
• Do not introduce Ubuntu-specific assumptions.
• Do not invent live-build, live-boot, initramfs, cryptsetup, systemd, GRUB, Debian package, or upstream tool behavior.
• Verify uncertain behavior against existing repository code or authoritative upstream documentation.
• Do not add phase-argument gates to live-boot or initramfs scripts. Execution phase is controlled by Debian hook placement.
• Preserve encrypted-root and encrypted-SquashFS architecture unless the task explicitly changes it.
• Prefer simple, explicit, inspectable Bash over clever abstraction.
• Do not use eval.
• Do not print secrets, private keys, passphrases, tokens, or sensitive environment values.

Repository map

Common areas:

• ciss_live_builder.sh, lib/*.sh: host-side orchestration and argument handling.
• makefile: local wrapper for composing and executing builder invocations.
• config/hooks/live/*.chroot: live-build chroot hooks.
• config/hooks/live/*.binary: live-build binary-image hooks.
• config/includes.chroot/etc/initramfs-tools/hooks/*: initramfs build hooks.
• config/includes.chroot/etc/initramfs-tools/scripts/*: initramfs boot scripts.
• config/includes.chroot/usr/lib/live/boot/*: live-boot runtime scripts.
• scripts/*: helper scripts or files copied into the generated image.
• docs/*: project documentation and conventions.

Working method

Before editing:

1. Inspect the relevant scripts, hooks, configuration files, documentation, tests, and naming conventions.
2. Identify the affected build or boot phase.
3. Give a concise implementation plan and list the likely files to touch, unless the change is trivial.

While editing:

• Keep changes minimal and local to the task.
• Preserve existing architecture, naming style, error handling, formatting, and security posture.
• Do not perform unrelated cleanup or formatting churn.
• Reuse existing helper functions for logging, fatal errors, validation, downloads, temporary files, and tool checks where available.
• Do not introduce new runtime dependencies unless technically necessary and justified.

After editing:

• Run only the narrowest checks that prove the change.
• Changed Bash files: run bash -n <file> and shellcheck <file> if ShellCheck is available.
• Changed POSIX shell files, if any exist and must remain POSIX: run sh -n <file>.
• Make wrapper or builder argument-composition changes: run the relevant dry-run or help/parser check, usually make dry-run if available.
• Changed Python files: run the repository's relevant Python checks if present.
• CLI or user-facing behavior changes: update usage() and relevant documentation.
• Live-build, initramfs, or ISO behavior changes: state the required Debian Trixie validation command. Do not run a full live build unless requested or necessary.

Bash conventions summary

See docs/CODING_CONVENTION.md for detail.

• Use Bash for new and modified project scripts unless an existing Debian interface file explicitly requires POSIX shell.
• Prefer set -Ceuo pipefail where feasible.
• Use declare for variables inside functions.
• Quote expansions unless word splitting or globbing is explicitly required.
• Prefer arrays where argument boundaries matter.
• Use [[ ... ]] for Bash conditionals.
• Use case for option dispatch and multi-branch string handling.
• Avoid parsing ls.
• Prefer command -v over which.
• Keep functions small and readable.
• End functions explicitly with return 0 where consistent with surrounding code.
• Code comments must be in English.

Security-sensitive areas

Before finalizing a change, check whether it affects:

• boot trust
• initramfs behavior
• live-boot runtime behavior
• cryptsetup/LUKS handling
• encrypted SquashFS handling
• key material
• remote unlock
• TLS, mTLS, signature, checksum, or provenance verification
• package sources or remote downloads
• network exposure
• file permissions
• persistence
• logging of sensitive values

If affected, document the concrete risk and mitigation in the final response.

Final response

Return a concise implementation report:

• changed files
• what changed
• checks run and result
• real remaining risks or follow-up steps

Do not claim success for checks that were not run.

---

no tracking | no logging | no advertising | no profiling | no bullshit