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. Use file tools to manage periodic tasks:

- **Add**: `edit_file` to append new tasks
- **Remove**: `edit_file` to delete completed tasks
- **Rewrite**: `write_file` to replace all tasks

When the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.

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

## How you were extended & tuned

`develop/` records how this instance was extended and tuned — skills, config, service work — with verified facts and a change log you can learn from (not the upstream code). See `develop/README.md`; read on demand.

## Explicit user details

Explicit user facts are stored in `keep.md`. Read at every turn.

## Projects (deep details)

More details about the user, projects, hardware etc. live in `projects/<name>/` (memory.md, state.md) — search those too.

## Knowledge base

`knowledge/` holds verified facts and measured values you can draw on when answering (e.g. notes on the models available to you). See `knowledge/README.md` for what's there; 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.

On the first safety-guard block: diagnose the cause before retrying — check a missing `working_dir` first, never re-send the same blocked form, and change one variable per test until the cause is identified.

## python — use uv

For all Python code (scripts, snippets, one-liners, tools) use `uv`,
not `python` / `python3` / `pip` directly.

- Run a script: `uv run script.py` (not `python script.py`)
- One-liner / snippet: `uv run --with <pkg> python -c '...'`
- Script with declared dependencies: `uv run --script script.py`
  (PEP 723 header inside the file)
- Add a project dependency: `uv add <pkg>` (not `pip install`)
- Remove: `uv remove <pkg>`
- Sync environment: `uv sync`
- Run a tool: `uv run pytest`, `uv run ruff`, `uv run mypy`, …
- REPL: `uv run python`

Do not use `pip`, `pip-tools`, `poetry`, `conda`, or the system `python`.
Reason: isolated, reproducible environments with no system-level side
effects, faster resolves, no "works on my machine" surprises.

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

Use these when the user explicitly asks for them or when they are the right tool for the job. Default remains Python for non-trivial scripts and Bash for very short shell snippets.

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