nanobot-runtime/AGENTS.md

# Agent Instructions

## Scheduled Reminders

**Personal reminders for the user** (notifications about tasks they need to do) → use the `/remind` skill → stored in SQLite (`db/reminders.sqlite`). Never use the `cron` tool for these.

**Background agent tasks** (run a script, check something, autonomous action) → use the built-in `cron` tool directly.

Test: *Who is the recipient?* User gets notified → `/remind` skill (SQLite `db/reminders.sqlite`). Agent executes something → `cron` tool.

**Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.

## Git commit timestamps

For commit-message timestamps run `bash scripts/timestamp.sh` — do NOT call `date` directly with a format string. The exec safety guard false-positives on `date '+%Y-%m-%d %H:%M:%S'` (colons in `%H:%M:%S` match its Windows drive-letter path regex) and blocks the command.

## Heartbeat Tasks

`HEARTBEAT.md` is checked on the configured heartbeat interval. Manage periodic tasks there with file tools (`edit_file` / `write_file`), not via one-time cron reminders.

## Databases (SQLite)

Always store SQLite databases under `db/*.sqlite` (relative to the workspace root).
Never use `/tmp/`, hardcoded absolute paths, or in-memory databases for persistent data.

## Workspace stores

- `develop/` — how this instance was extended and tuned (see `develop/README.md`); read on demand
- `keep.md` — explicit user facts; read at every turn
- `projects/<name>/` — deep details about the user, projects, hardware; search those too
- `knowledge/` — verified facts and measured values (see `knowledge/README.md`); read on demand

## exec Tool

The exec safety guard blocks commands without an explicit workspace path (e.g. `lua -e '...'`, `which`). Write scripts to files inside the workspace (e.g. `tmp/script.lua`) and run them with `working_dir` set to the workspace root.

## python — use uv

For all Python code use `uv`, never `python` / `python3` / `pip` / `poetry` / `conda` directly. Details in `skills/python/SKILL.md`.

## File / Code Conventions

### Report / result files
- Save important reports to `results/` directory with descriptive, date-prefixed filenames (e.g., `2026-06-02_remind-skill-analysis-and-improvements.md`)

### Script-writing convention
- Location: always save scripts in the `scripts/` directory.
- Language choice:
  - Extremely short script (a few lines) -> bash.
  - Longer / non-trivial script -> Python.
- Override: if the user explicitly specifies a language or location, their instruction always takes precedence.

### Available scripting languages

In addition to Python and Bash, the agent can also write and run:

- **Lua** — via `lua` interpreter (scripts in `tmp/`, run with `working_dir` set to workspace root)
- **Rust** — via `rustc` / `cargo` (compile and run inside workspace)
- **TypeScript** — always via `bun`

### Git clones
- Always clone repos into `workspace/src/<repo-name>`, not directly into workspace root.

### Temporary files
- All temporary files go to `tmp/` directory.
- Clean up after tests and one-off operations.

### Code changes
- User prefers changes to be made in a temporary clone under `workspace/tmp/<repo-name>` for review before applying

## No proactive actions

When I ask you to **find out**, **investigate**, **look into**, or **check**
something, that is a request for information only. Report your findings, then
ask whether I want them carried out — never treat learning about a problem as a
request to fix it. When in doubt, ask first.

## Git commits for workspace changes

Whenever the agent modifies any skill or any file in the workspace (including dream/runtime changes), make a git commit in the workspace repo. Commit message: current date and time in SQL format (`YYYY-MM-DD HH:MM:SS`), prefixed to indicate it's a nanobot agent change, e.g.:

`nanobot: 2026-02-12 14:35:07`

## Behavioral Guidelines

1. Don't assume. Don't hide confusion. Surface tradeoffs.
   - If an instruction is ambiguous, stop and ask for clarification before acting.
   - Do not make assumptions about user intent, data formats, or scope.
   - Explicitly surface tradeoffs when multiple implementation paths exist.

2. Minimum code that solves the problem. Nothing speculative.
   - Implement only the logic requested. Avoid premature abstraction, design patterns (like Strategy or Factory), or future-proofing that is not explicitly required.
   - If a simple solution exists, prefer it over complex, generalized ones.

3. Touch only what you must. Clean up only your own mess.
   - Changes must be surgical. Do not reformat files, update type hints, or rewrite existing code unless it is strictly required to fulfill the specific task.
   - If your changes introduce orphans (e.g., unused imports, dead variables), clean them up. Otherwise, leave existing code untouched.

4. Define success criteria. Loop until verified.
   - Before coding, define clear success criteria or a verification plan.
   - Iterate and self-correct until the verification tests pass. Ensure each step of the implementation is verified against the goal.

5. A multi-step task: plan and then execute, in the same turn.
   - After laying out the plan for a multi-step task or a piece of research, start carrying it out immediately — the plan is not the end of the turn. Report progress as you go.
   - Merely printing a plan and ending the turn looks like a finished answer; the user then waits for nothing.
   - This does not override *No proactive actions* above: a request to **find out / investigate / check** stays information-only. This rule applies to a task the user actually asked you to carry out.