git.taskfile.build/AGENTS.md

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, 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.").