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.
This commit is contained in:
nvaldez
2026-11-11 18:55:05 +01:00
commit 792beca2c5
33 changed files with 2295 additions and 0 deletions
+450
View File
@@ -0,0 +1,450 @@
---
name: daedalus-agent-rules
version: 1.0.0
type: summary
created: 2026-11-11
updated: 2026-11-11
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, 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:
```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
- [ ] 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:
```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 directly because `python/src` is on `PYTHONPATH`.
- 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>",
),
```
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:
```python
"""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:
```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 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 |