--- name: daedalus-agent-rules version: 1.1.0 type: summary created: 2026-11-11 updated: 2026-11-18 tags: [agents, rules, scripts, cli] --- # daedalus Agent Rules - [1. Overview](#1-overview) - [1.1 Rule References](#11-rule-references) - [1.2 Sources of Truth](#12-sources-of-truth) - [2. Basic Rules (MANDATORY)](#2-basic-rules-mandatory) - [2.1 Change Lifecycle](#21-change-lifecycle) - [2.2 Testing](#22-testing) - [2.3 Commit](#23-commit) - [3. Environment Setup](#3-environment-setup) - [4. Repository Structure](#4-repository-structure) - [5. Integrating a Script](#5-integrating-a-script) - [5.1 Inputs and Checklist](#51-inputs-and-checklist) - [5.2 Integration Contract](#52-integration-contract) - [5.3 Choosing the Name and Type](#53-choosing-the-name-and-type) - [5.4 File Templates](#54-file-templates) - [5.5 Register and Document](#55-register-and-document) - [5.6 Tests](#56-tests) - [5.7 Importing an Existing Script](#57-importing-an-existing-script) - [6. Code Conventions](#6-code-conventions) - [6.1 All Files](#61-all-files) - [6.2 Python](#62-python) - [6.3 Shell, PowerShell, Batch](#63-shell-powershell-batch) - [7. Quality Gates](#7-quality-gates) - [8. Anti-Patterns](#8-anti-patterns) - [9. Quick Reference](#9-quick-reference) ## 1. Overview daedalus keeps loose personal scripts in one repository, each with tests, and runs any of them with `daedalus [args...]`. The same checkout runs on a Windows workstation and on a Linux host. This file tells an agent what must hold before it changes the repository, and how to integrate a new script. ### 1.1 Rule References Refer to rules in this file as `daedalus agent rule N.M` (for example `daedalus agent rule 5.2`) to keep them apart from other `AGENTS.md` files in the workspace. ### 1.2 Sources of Truth | Topic | File | | --- | --- | | Behavior, layout, registry, runners, packaging | [SPEC](./SPEC.md) | | Script catalog shown to users | [README](./README.md) | | Install, usage, development setup | [INSTALL](./INSTALL.md) | When this file and [SPEC](./SPEC.md) disagree, SPEC wins. Fix this file. ## 2. Basic Rules (MANDATORY) ### 2.1 Change Lifecycle Every change that alters behavior follows these steps, in order: - **Spec.** Read the [SPEC](./SPEC.md) section for the area. When the change is not described there, update SPEC first. - **Tests.** Add or change tests that fail without the change. - **Code.** Make the smallest change that makes them pass. - **Docs.** Update [README](./README.md) and [INSTALL](./INSTALL.md) when user-facing behavior changed. - **Version.** Bump `version` in `pyproject.toml` when a script or the CLI changed: patch for a fix, minor for a new script, major for a breaking CLI change. Without the bump, `pipx upgrade daedalus` does not pick up the change. - **Verify.** Run `python autotest.py` (daedalus agent rule 2.2). When a check fails, read its output, fix the cause, and run it again; never disable a check. Check `daedalus --help` for a new script. - **Report.** Tell the user the command name, the files added or changed, the test result, and how to run the result (`daedalus ...`). Adding a script that fits [SPEC](./SPEC.md) section 6 needs no SPEC change. ### 2.2 Testing - Run `python autotest.py` from the repository root before finishing any task that changes files. CI runs the same command. - Run a subset while iterating: `python autotest.py pytest markdown`. - Never lower `MIN_COVERAGE_PERCENT` in `autotest.py`. Raise it when new tests push coverage up. ### 2.3 Commit - Commit only when the user asks. - Print the commit message at the end of the reply. ## 3. Environment Setup ```bash python -m venv .venv source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements.txt pip install -e . # daedalus command runs the checkout ``` - Python 3.11 or newer. - On Windows the workspace shell is PowerShell: chain commands with `;`, not `&&`. - Without an install, run the CLI with `python -m daedalus` from the repository root. ## 4. Repository Structure ```text daedalus/ ├── bin/ # Launchers: daedalus (bash), daedalus.bat ├── daedalus/ # CLI package: cli.py, registry.py, runners.py, │ # run_python_script.py, daedalus_logging/, tests/ ├── python/ │ ├── src// # One folder per Python script │ └── tests/ # pytest tests for python/src (and .ps1/.bat scripts) ├── bash/ # *.sh scripts; tests/ holds their pytest tests ├── powershell/ # *.ps1 scripts ├── batch/ # *.bat scripts (CRLF) ├── ci/ # sanity and lint checks used by autotest.py ├── autotest.py # Every check, local and CI ├── pyproject.toml # Package, version, script folders as package data ├── README.md # Script catalog ├── INSTALL.md # Install and development └── SPEC.md # Repository specification ``` - Only `python/src/`, `bash/`, `powershell/`, and `batch/` are shipped in the wheel (under `daedalus/_library/`). A script anywhere else is not installed. - Tests under `*/tests/` are not packaged. ## 5. Integrating a Script ### 5.1 Inputs and Checklist Before writing anything, know: - The script: a file path, a paste, or a description of what to build. - The command name. Default to the file stem in `snake_case`. It must match `^[a-z][a-z0-9_-]*$` and not already be in `SCRIPTS`. - The type: Python, bash, PowerShell, or batch. Prefer Python when the script must run on both Windows and Linux. - A one-line description for `daedalus --list`. - The categories the script belongs to. The default is `general`; pick labels that say where the script fits (`media`, `linux`, ...). A label may never equal a script name. Ask the user only when the name or the type cannot be inferred. Track the work with this checklist: ```text - [ ] File placed and runs on its own - [ ] Entry added to SCRIPTS in daedalus/registry.py - [ ] README row and usage section - [ ] Tests written and passing - [ ] daedalus. entry in pyproject.toml (Python scripts) - [ ] version bumped in pyproject.toml - [ ] python autotest.py passes - [ ] daedalus --help works ``` ### 5.2 Integration Contract A script is integrated when all of these hold. Tests enforce the ones marked "test". | Rule | Enforced by | | --- | --- | | File is in the folder for its type (daedalus agent rule 5.3) | Packaging test | | File runs on its own, without daedalus | Review | | One entry in `SCRIPTS` in `daedalus/registry.py` | Registry test | | Name matches `^[a-z][a-z0-9_-]*$` | Registry test | | `path` is repo-relative with forward slashes | Registry test | | `description` is one non-empty line | Registry test | | `categories` are non-empty labels, none equal to a script name | Registry test | | File suffix has a runner (`.py`, `.sh`, `.ps1`, `.bat`) | Registry test | | A row for the name in the README "Available scripts" table | Registry test | | Own tests for the script's logic | Review, coverage | | `version` in `pyproject.toml` bumped | Review | | `python autotest.py` passes | CI | ### 5.3 Choosing the Name and Type | Type | Location | Runner | | --- | --- | --- | | Python | `python/src//.py` | `DAEDALUS_PYTHON` or current Python, via `run_python_script.py` | | bash | `bash/.sh` | `DAEDALUS_BASH`, Git Bash, then `bash` | | PowerShell | `powershell/.ps1` | `pwsh`, then `powershell` | | Batch | `batch/.bat` | `cmd /c`, Windows only | - Prefer Python for anything that must work on both Windows and Linux. - The command name, the file stem, and (for Python) the folder name are the same string. - Choose a name that says what the script does (`backup_configs`, not `tool1`). Check `daedalus --list` for clashes. ### 5.4 File Templates | Type | Path | | --- | --- | | Python | `python/src//.py` | | bash | `bash/.sh` | | PowerShell | `powershell/.ps1` | | Batch | `batch/.bat` (CRLF, Windows only) | Python template: ```python """ Run via daedalus: ``daedalus [args]`` (see daedalus README). """ from __future__ import annotations import argparse import logging import sys LOGGER = logging.getLogger(__name__) def parse_args(argv: list[str] | None) -> argparse.Namespace: """Parse command-line arguments.""" parser = argparse.ArgumentParser(prog="", description=__doc__.splitlines()[0]) parser.add_argument("-q", "--quiet", action="store_true", help="only log warnings and errors") return parser.parse_args(argv) def main(argv: list[str] | None = None) -> int: """CLI entry point; return the exit code.""" args = parse_args(argv) logging.basicConfig(level=logging.WARNING if args.quiet else logging.INFO, format="%(levelname)-5s %(message)s") return 0 if __name__ == "__main__": sys.exit(main()) ``` - `prog=""` makes `--help` show the daedalus command name. - Shared helpers go in their own package under `python/src/`; scripts import them as `daedalus.` (SPEC section 10). The child gets `REPO_ROOT` on `PYTHONPATH`, so the import works in a checkout and an install alike. - Python scripts run through `run_python_script.py` and get the `daedalus_logging` setup (file `~/.daedalus/debug.log` + stderr, `DAEDALUS_LOGLEVEL`, `DAEDALUS_NO_LOGGING`) unless they configure logging themselves. - Standard library only. Lazy `%` logging. Type hints in every docstring. bash template: ```bash #!/usr/bin/env bash # set -euo pipefail usage() { echo "usage: [-h] " } main() { if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then usage return 0 fi } main "$@" ``` Stage it executable: `git add --chmod=+x bash/.sh`. PowerShell template: ```powershell <# .SYNOPSIS #> param( [switch]$Quiet ) $ErrorActionPreference = 'Stop' ``` ### 5.5 Register and Document Add one entry to `SCRIPTS` in `daedalus/registry.py`, keeping keys sorted: ```python "": Script( path="python/src//.py", description="", categories="