Files
daedalus/AGENTS.md
T
nvaldez 792beca2c5 daedalus 0.0.0: empty template - one CLI, many small scripts, each with tests
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.
2026-11-11 18:55:11 +01:00

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
agents
rules
scripts
cli

daedalus Agent Rules

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 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 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

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

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/, 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.

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, 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:

"""<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 directly because python/src is on PYTHONPATH.
  • 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, 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 <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. .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 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 (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