b71a513c36
Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
473 lines
16 KiB
Markdown
473 lines
16 KiB
Markdown
---
|
|
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 <name> [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 <name> --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 <name> ...`).
|
|
|
|
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/<name>/ # 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.<folder> entry in pyproject.toml (Python scripts)
|
|
- [ ] version bumped in pyproject.toml
|
|
- [ ] python autotest.py passes
|
|
- [ ] daedalus <name> --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/<name>/<name>.py` | `DAEDALUS_PYTHON` or current Python, via `run_python_script.py` |
|
|
| bash | `bash/<name>.sh` | `DAEDALUS_BASH`, Git Bash, then `bash` |
|
|
| PowerShell | `powershell/<name>.ps1` | `pwsh`, then `powershell` |
|
|
| Batch | `batch/<name>.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/<name>/<name>.py` |
|
|
| bash | `bash/<name>.sh` |
|
|
| PowerShell | `powershell/<name>.ps1` |
|
|
| Batch | `batch/<name>.bat` (CRLF, Windows only) |
|
|
|
|
Python template:
|
|
|
|
```python
|
|
"""<One line: what the script does.>
|
|
|
|
Run via daedalus: ``daedalus <name> [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 <name> command-line arguments."""
|
|
parser = argparse.ArgumentParser(prog="<name>", 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="<name>"` makes `--help` show the daedalus command name.
|
|
- Shared helpers go in their own package under `python/src/`; scripts
|
|
import them as `daedalus.<folder>` (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
|
|
# <One line: what the script does.>
|
|
set -euo pipefail
|
|
|
|
usage() {
|
|
echo "usage: <name> [-h] <args>"
|
|
}
|
|
|
|
main() {
|
|
if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
|
|
usage
|
|
return 0
|
|
fi
|
|
}
|
|
|
|
main "$@"
|
|
```
|
|
|
|
Stage it executable: `git add --chmod=+x bash/<name>.sh`.
|
|
|
|
PowerShell template:
|
|
|
|
```powershell
|
|
<#
|
|
.SYNOPSIS
|
|
<One line: what the script does.>
|
|
#>
|
|
param(
|
|
[switch]$Quiet
|
|
)
|
|
$ErrorActionPreference = 'Stop'
|
|
```
|
|
|
|
### 5.5 Register and Document
|
|
|
|
Add one entry to `SCRIPTS` in `daedalus/registry.py`, keeping keys
|
|
sorted:
|
|
|
|
```python
|
|
"<name>": Script(
|
|
path="python/src/<name>/<name>.py",
|
|
description="<one line, same as README>",
|
|
categories="<label>", # or a tuple; default is "general"
|
|
),
|
|
```
|
|
|
|
Do not edit `cli.py` or `runners.py`. The suffix picks the runner.
|
|
|
|
For a Python script, also add the folder to `pyproject.toml` as an
|
|
installed package (SPEC section 9): entries `"daedalus.<folder>"` in
|
|
`[tool.setuptools].packages` and
|
|
`"daedalus.<folder>" = "python/src/<folder>"` in
|
|
`[tool.setuptools.package-dir]`.
|
|
|
|
In `README.md`:
|
|
|
|
- Add a row to the "Available scripts" table, sorted by name:
|
|
`` | `<name>` | Python | <categories> | <description> | ``. The
|
|
registry test looks for the exact text `` | `<name>` | ``.
|
|
- When the script takes arguments, add a `### <name>` section after the
|
|
table: what it does, example `daedalus <name> ...` calls in a `bash`
|
|
block, and an argument table. Follow the existing sections, if any.
|
|
|
|
### 5.6 Tests
|
|
|
|
| Type | Test file | How |
|
|
| --- | --- | --- |
|
|
| Python | `python/tests/test_<name>.py` | `from daedalus.<name> import <name>`, call functions and `main([...])` |
|
|
| bash | `bash/tests/test_<name>.py` | `subprocess.run` with `runners.find_bash()`; skip when bash is missing |
|
|
| PowerShell, batch | `python/tests/test_<name>.py` | `subprocess.run` via `runners.build_command`; skip when the interpreter or Windows is missing |
|
|
|
|
Cover the pure logic and `main` with argument lists. Use `tmp_path` for
|
|
files and `monkeypatch` for environment variables. Tests must not need
|
|
another machine, the network, or an interactive terminal.
|
|
|
|
Python test skeleton:
|
|
|
|
```python
|
|
"""Tests for <name>.
|
|
|
|
<what the tests cover>.
|
|
"""
|
|
from daedalus.<name> import <name>
|
|
|
|
|
|
def test_main_returns_zero():
|
|
"""Default run succeeds."""
|
|
assert <name>.main([]) == 0
|
|
```
|
|
|
|
Shell-out skeleton for bash:
|
|
|
|
```python
|
|
"""Tests for bash/<name>.sh.
|
|
|
|
<what the tests cover>.
|
|
"""
|
|
import subprocess
|
|
|
|
import pytest
|
|
|
|
from daedalus import REPO_ROOT
|
|
from daedalus import runners
|
|
|
|
SCRIPT = REPO_ROOT / "bash" / "<name>.sh"
|
|
|
|
|
|
@pytest.fixture(name="bash")
|
|
def fixture_bash() -> str:
|
|
"""bash interpreter, or skip."""
|
|
try:
|
|
return runners.find_bash()
|
|
except runners.RunnerError:
|
|
pytest.skip("bash not available")
|
|
|
|
|
|
def test_help(bash):
|
|
"""--help exits 0 and prints usage."""
|
|
result = subprocess.run([bash, str(SCRIPT), "--help"], capture_output=True, text=True, check=False)
|
|
assert result.returncode == 0
|
|
assert "usage" in result.stdout
|
|
```
|
|
|
|
### 5.7 Importing an Existing Script
|
|
|
|
When the user brings a script from elsewhere (another repo, another
|
|
machine, a paste):
|
|
|
|
- Keep its behavior. Restructure only as far as the contract needs: a
|
|
`main(argv)` entry point for Python, no hard-coded absolute paths, no
|
|
secrets.
|
|
- Move hard-coded hosts, passwords, and paths to arguments or environment
|
|
variables. Never commit credentials.
|
|
- Split pure logic (parsing, formatting, computing) from I/O, so it can be
|
|
tested without a terminal, the network, or a specific machine.
|
|
- Mention the origin in the module docstring, not in a comment per line.
|
|
|
|
## 6. Code Conventions
|
|
|
|
### 6.1 All Files
|
|
|
|
- LF line endings everywhere except `*.bat`, which must be CRLF.
|
|
`.gitattributes` enforces both on checkout.
|
|
- Markdown lists use dashes. markdownlint runs with MD013 and MD033 off.
|
|
- No file over 2 MB, no private keys.
|
|
|
|
### 6.2 Python
|
|
|
|
- Target Python 3.11. PEP 8 (pycodestyle with the repo ignore list).
|
|
- Standard library imports use `import module`.
|
|
- Logging uses lazy `%` formatting: `LOGGER.info("wrote %s", path)`.
|
|
- Type hints and a docstring on every function.
|
|
- No runtime dependencies outside the standard library. The wheel declares
|
|
`dependencies = []`; a script that needs a package must say so in its
|
|
`--help` and fail with a clear message when it is missing.
|
|
|
|
### 6.3 Shell, PowerShell, Batch
|
|
|
|
- bash scripts start with `#!/usr/bin/env bash` and `set -euo pipefail`,
|
|
pass shellcheck, and are committed executable:
|
|
`git add --chmod=+x bash/<name>.sh`.
|
|
- PowerShell scripts declare a `param()` block and run under `pwsh` on
|
|
Linux unless they are Windows-only by nature.
|
|
- Batch scripts are Windows-only and CRLF.
|
|
|
|
## 7. Quality Gates
|
|
|
|
`python autotest.py` runs these checks in parallel:
|
|
|
|
| Check | Rule |
|
|
| --- | --- |
|
|
| `sanity` | Changed files: line endings, no private keys, under 2 MB |
|
|
| `python_syntax` | Every `*.py` parses |
|
|
| `pycodestyle` | PEP 8 with the repo ignore list |
|
|
| `shellcheck` | Every shell script, including suffixless launchers |
|
|
| `json`, `yaml` | Every file loads |
|
|
| `markdown` | markdownlint |
|
|
| `pytest` | All tests pass; coverage of `ci`, `daedalus`, `python/src` at least `MIN_COVERAGE_PERCENT` |
|
|
|
|
A failing check is reported to the user with its output. Never skip or
|
|
disable a check to make a run pass.
|
|
|
|
## 8. Anti-Patterns
|
|
|
|
- A script outside `python/src/`, `bash/`, `powershell/`, or `batch/`.
|
|
- Registry `path` with backslashes or an absolute path.
|
|
- A runner chosen by anything other than the file suffix.
|
|
- A top-level import from `python/src` (use `daedalus.<folder>`;
|
|
SPEC section 10).
|
|
- A category label that equals a script name.
|
|
- A script that only works through daedalus (imports from `daedalus`,
|
|
reads `LIBRARY_ROOT`).
|
|
- Tests that need another machine, the network, or an interactive terminal without a
|
|
skip condition.
|
|
- Editing `daedalus/cli.py` or `daedalus/runners.py` to add a script.
|
|
Adding a script touches only the script, its tests, `registry.py`,
|
|
`README.md`, and `pyproject.toml`.
|
|
- Lowering `MIN_COVERAGE_PERCENT`.
|
|
|
|
## 9. Quick Reference
|
|
|
|
| Task | Action |
|
|
| --- | --- |
|
|
| Add or import a script | Follow [section 5](#5-integrating-a-script) (daedalus agent rule 5.1) |
|
|
| Change CLI or runner behavior | Update [SPEC](./SPEC.md) first (daedalus agent rule 2.1) |
|
|
| Register a script | One `Script(...)` entry in `daedalus/registry.py` |
|
|
| Document a script | Row and usage section in [README](./README.md) |
|
|
| Before finishing | `python autotest.py` |
|
|
| Ship a change | Bump `version` in `pyproject.toml` |
|
|
| Commit | Only when asked |
|