Sanitized open-source starter: renamed to daedalus, Norse-free of internal references, AI attribution stripped, skill merged into AGENTS.md, CI converted to Gitea Actions. No registered scripts yet.
15 KiB
name, version, type, created, updated, tags
| name | version | type | created | updated | tags | ||||
|---|---|---|---|---|---|---|---|---|---|
| daedalus-agent-rules | 1.0.0 | summary | 2026-11-11 | 2026-11-11 |
|
daedalus Agent Rules
- 1. Overview
- 2. Basic Rules (MANDATORY)
- 3. Environment Setup
- 4. Repository Structure
- 5. Integrating a Script
- 6. Code Conventions
- 7. Quality Gates
- 8. Anti-Patterns
- 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 |
| Script catalog shown to users | README |
| Install, usage, development setup | INSTALL |
When this file and SPEC 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 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 and INSTALL when user-facing behavior changed.
- Version. Bump
versioninpyproject.tomlwhen 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 daedalusdoes 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. Checkdaedalus <name> --helpfor 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 section 6 needs no SPEC change.
2.2 Testing
- Run
python autotest.pyfrom 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_PERCENTinautotest.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
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 daedalusfrom the repository root.
4. Repository Structure
daedalus/
├── bin/ # Launchers: daedalus (bash), daedalus.bat
├── daedalus/ # CLI package: cli.py, registry.py, runners.py, 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/, andbatch/are shipped in the wheel (underdaedalus/_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 inSCRIPTS. - 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.
Ask the user only when the name or the type cannot be inferred. Track the work with this checklist:
- [ ] File placed and runs on its own
- [ ] Entry added to SCRIPTS in daedalus/registry.py
- [ ] README row and usage section
- [ ] Tests written and passing
- [ ] 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 |
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 |
Current Python, python/src on PYTHONPATH |
| 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, nottool1). Checkdaedalus --listfor 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:
"""<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--helpshow the daedalus command name.- Shared helpers go in their own package under
python/src/; scripts import them directly becausepython/srcis onPYTHONPATH. - Standard library only. Lazy
%logging. Type hints in every docstring.
bash template:
#!/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:
<#
.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:
"<name>": Script(
path="python/src/<name>/<name>.py",
description="<one line, same as README>",
),
Do not edit cli.py or runners.py. The suffix picks the runner.
In README.md:
- Add a row to the "Available scripts" table, sorted by name:
| `<name>` | Python | <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, exampledaedalus <name> ...calls in abashblock, and an argument table. Follow the existing sections, if any.
5.6 Tests
| Type | Test file | How |
|---|---|---|
| Python | python/tests/test_<name>.py |
from <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:
"""Tests for <name>.
<what the tests cover>.
"""
from <name> import <name>
def test_main_returns_zero():
"""Default run succeeds."""
assert <name>.main([]) == 0
Shell-out skeleton for bash:
"""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..gitattributesenforces 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--helpand fail with a clear message when it is missing.
6.3 Shell, PowerShell, Batch
- bash scripts start with
#!/usr/bin/env bashandset -euo pipefail, pass shellcheck, and are committed executable:git add --chmod=+x bash/<name>.sh. - PowerShell scripts declare a
param()block and run underpwshon 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/, orbatch/. - Registry
pathwith backslashes or an absolute path. - A runner chosen by anything other than the file suffix.
- A script that only works through daedalus (imports from
daedalus, readsLIBRARY_ROOT). - Tests that need another machine, the network, or an interactive terminal without a skip condition.
- Editing
daedalus/cli.pyordaedalus/runners.pyto add a script. Adding a script touches only the script, its tests,registry.py,README.md, andpyproject.toml. - Lowering
MIN_COVERAGE_PERCENT.
9. Quick Reference
| Task | Action |
|---|---|
| Add or import a script | Follow section 5 (daedalus agent rule 5.1) |
| Change CLI or runner behavior | Update SPEC 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 |
| Before finishing | python autotest.py |
| Ship a change | Bump version in pyproject.toml |
| Commit | Only when asked |