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:
@@ -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 |
|
||||
Reference in New Issue
Block a user