116 lines
4.8 KiB
Markdown
116 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## General agent guidance
|
|
|
|
This section outlines the universal rules and expectations for any LLM agent working within this repository.
|
|
|
|
**Safety and Quality First:** The highest priority is to produce secure, well-documented, and high-quality code. Do not introduce vulnerabilities, hardcoded secrets, or unreadable code.
|
|
|
|
**Propose a Plan:** For any new task, first provide a brief plan of action. This plan should clearly outline the intended changes and the rationale behind them.
|
|
|
|
**Maintain Context:** Before making any changes, an agent must read and understand the relevant files, including the project's main documentation and existing code structure.
|
|
|
|
**Be Sparse:** Only introduce new code if needed. Comment only what is worth commenting. When testing focus on the business use case. When writing documentations keep the explanation to a minimum.
|
|
|
|
## Project structure
|
|
|
|
The project follows the Zensical static site generator structure:
|
|
|
|
```
|
|
taskfile.build/
|
|
├── docs/ # Documentation source files
|
|
│ ├── img/ # Image assets
|
|
│ ├── javascripts/ # JavaScript files
|
|
│ └── stylesheets/ # CSS stylesheets
|
|
│ └── style.css # Main stylesheet
|
|
├── site/ # Generated site (build output)
|
|
├── zensical.toml # Zensical configuration
|
|
├── README.md # Main documentation
|
|
├── AGENTS.md # Agent guidance (this file)
|
|
├── examples.md # Examples documentation
|
|
├── library.md # Library documentation
|
|
├── patterns.md # Patterns documentation
|
|
├── usage.md # Usage documentation
|
|
├── package.json # Node.js dependencies
|
|
└── task # Main task script
|
|
```
|
|
|
|
The site generates documentation pages from markdown files using Zensical, with a responsive layout that includes navigation and content areas.
|
|
|
|
## Environment & tooling
|
|
|
|
### Taskfile
|
|
|
|
This project uses the <https://taskfile.build/> standard.
|
|
|
|
The `./task` file is a bash script that provides all functions necessary to work with this project.
|
|
|
|
Always try to run a command with the `./task` file script.
|
|
|
|
### Session Info (pi harness)
|
|
|
|
Inside the **pi** harness, the model ID is in `$PI_MODEL` (e.g. `moonshotai/Kimi-K2.6`), and the session log is at `$PI_SESSION_FILE`. That JSONL file contains token usage in the `message.usage` fields (`input` and `output`). When completing a prompt file, extract the model and cumulative token counts from these sources.
|
|
|
|
### Jupyter Notebooks
|
|
|
|
**Run with timeout**: Run the notebook with `timeout 10 task run-jupyter-notebook <path> [env]`.
|
|
|
|
**Edit with MCP**: Launch Jupyter Lab and use the builtin MCP server to edit the notebooks.
|
|
|
|
## Coding conventions
|
|
|
|
### Bash
|
|
|
|
The following guideline is heavily based on the [Bash Style Guide | ysap.sh](https://style.ysap.sh/), which should be considered the primary reference for style. Adhere to the following principles to ensure scripts are safe, predictable, and maintainable.
|
|
|
|
**Shebang:** Start scripts with `#!/usr/bin/env bash` for portability.
|
|
|
|
**Quoting:** This is critical.
|
|
|
|
- Use double quotes `"` for strings that require variable expansion.
|
|
- Use single quotes `'` for all other strings.
|
|
|
|
**Always quote variable expansions** `"$var"` to prevent word-splitting and globbing issues.
|
|
|
|
**Variables:** Distinct between local and environment vars.
|
|
|
|
- Use `local` for all variables inside functions.
|
|
- Use lowercase names for local variables (e.g., `buildx_output`).
|
|
- Use uppercase names for environment variables (e.g. `export BUILDX_PLATFORM`)
|
|
|
|
**Functions:**
|
|
|
|
- Do not use the `function` keyword.
|
|
- Use `my-func() { ... }` syntax.
|
|
- Function names are in kebab case.
|
|
|
|
**Conditionals:**
|
|
|
|
- Always use `[[ ... ]]` for conditional testing, not `[ ... ]` or `test`.
|
|
- Use `((...))` for arithmetic comparisons (e.g., `((a > b))`).
|
|
- When replacing `[]` with `[[]]` make sure to escape the brackets. The `[]` is a regex filter.
|
|
|
|
**Command Substitution:**
|
|
|
|
- Always use `$(...)` for command substitution, not backticks.
|
|
|
|
**Arrays:**
|
|
|
|
- Use Bash arrays to manage lists of items instead of space-separated strings.
|
|
- Iterate over arrays using `for item in "${my_array[@]}"; do ... done`.
|
|
|
|
**Avoid External Commands:**
|
|
|
|
- Use Bash's built-in parameter expansion for string manipulation (e.g., `${var/foo/bar}`).
|
|
- Use globbing (`*`) to iterate over files, not `ls`.
|
|
- Avoid `cat` when a command can read a file directly (e.g., `grep "pattern" file`).
|
|
|
|
**eval:** Never use `eval`.
|
|
|
|
**Logging:**
|
|
|
|
- Use single quotes for outputs without variables.
|
|
- Use double quotes for outputs with variables.
|
|
- Do not finish sentence with a dot if action is following (e.g. `"Backup file"`).
|
|
- Finish sentence with a dot if echo is after action (e.g. `"Backup finished."`).
|