AGENTS Instructions

August 29, 2026 · View on GitHub

This file provides guidance for AI coding assistants working with this project.

MANDATORY: Action Logging

This is non-negotiable. Log before you start, log as you work, log when you finish.

Every AI session MUST produce a log entry in .agents/logs/YYYY-MM-DD.md. This is not optional documentation — it is a required action, executed by the agent itself, not left to the human.

Procedure

Step 1 — Before touching any file:

# Get today's filename
date '+%Y-%m-%d' # e.g. 2026-03-16

If .agents/logs/YYYY-MM-DD.md does not exist → create it with the header:
```
# AI Work Log - YYYY-MM-DD
```
If it already exists → append to it (do NOT overwrite)

Step 2 — Open your entry immediately:

Append a new entry header with the current ISO timestamp, the user's prompt, and the prompter's name.

Resolve the prompter name from git config user.name. If that is empty or unavailable, ask the user for their name before continuing.

## HH:MM:SS+TZ

### Prompt

> <exact user request, verbatim or faithfully paraphrased>

### Prompter

<name from `git config user.name`, or as provided by the user>

### Model

<model name and version> via <editor/tool> (e.g. Claude Sonnet 4.6 via opencode)

Step 3 — Log each action as you perform it:

After every meaningful action, append to the ### Actions section. Do not batch everything at the end — if the session is interrupted, the log must still reflect what was done.

Step 4 — Close the entry when done:

Append the ### Outcome section:

### Outcome

<✅ / ⚠️ / ❌> <one-line summary of what was achieved or what failed>

Log Format (AI-authored)

## 2026-03-16T20:15:00+11:00

### Prompt

> Add tool-runner skill with Bun/Node fallback chains

### Prompter

Jane Doe

### Model

Claude Sonnet 4.6 via opencode

### Actions

- Created `.agents/skills/tool-runner/SKILL.md` — main skill documentation with fallback patterns
- Created `.agents/skills/tool-runner/assets/tool-runner.sh` — standalone bash script for tool selection
- Created `.agents/skills/tool-runner/assets/validate-tools.sh` — validation script for tool availability
- Modified `AGENTS.md` — registered skill in Project Skills table
- Decision: used `command -v` over `which` for POSIX compliance across Linux/macOS/Windows

### Outcome

✅ Skill created and committed, all pre-commit hooks passed

What Counts as a Loggable Action

Always log:

Every file created — name, purpose, approximate scope
Every file modified — name, what changed and why
Every decision made — especially when choosing between alternatives
Every command run with a non-trivial outcome (tool installs, test runs, linter results)
Anything rejected or changed from the original approach, and the reason

Do NOT log:

Trivial auto-fixes by pre-commit hooks (formatting, whitespace)
Reading files for context (unless the read revealed something decision-relevant)
Intermediate tool calls that produced no output or change

Additional Materials

Place any other relevant documents (prompts, examples, references, generated docs) in the .agents/ folder.

MANDATORY: AI Co-authored-by Trailer

Every commit made with AI assistance MUST include a Co-authored-by trailer. No exceptions.

Format:

Co-authored-by: <Model Name> via <Tool> <noreply@provider-domain>

Provider noreply addresses:

Provider	noreply address
Anthropic (Claude)	`noreply@anthropic.com`
Cursor	`cursoragent@cursor.com`
Google (Gemini)	`noreply@google.com`
Meta (Llama)	`noreply@meta.com`
Microsoft (Copilot)	`noreply@microsoft.com`
Mistral	`noreply@mistral.ai`
OpenAI (GPT / o-series)	`noreply@openai.com`
xAI (Grok)	`noreply@x.ai`

If a provider is not listed above, use the provider's official noreply address. Multiple co-authors can be listed by repeating the Co-authored-by line for each author.

Examples:

feat(precommit): add spell checking to commit messages

Co-authored-by: Claude Sonnet 4.6 via opencode <noreply@anthropic.com>

fix(cspell): resolve configuration issue

Co-authored-by: Composer via Cursor <cursoragent@cursor.com>

Rules:

Use the exact model name and version you are running as (e.g. Claude Sonnet 4.6, not just Claude)
Use the tool name as it is commonly known (e.g. opencode, Cursor, Copilot, Zed)
If the model version is unknown, use the model family name (e.g. Claude Sonnet)
One trailer per AI model involved
Never omit this trailer when the commit was AI-assisted — this is how git history stays honest

Setup: skills and MCP

Before substantive work, ensure project skills and MCP servers are installed.

From the repository root, run either:
```
apm install
```
or, if apm is not on PATH:
```
uvx --from apm-cli apm install
```
Reload the agent (new chat / restart the agent session) so installed skills and MCP servers are picked up.

Configuration lives in apm.yml. Do not skip this when skills or MCP tools are missing or stale.

Project Context

Project Type: Project generated from copier-mr-minimal
Key Technologies: Nix flake + Blueprint (nix/), git-hooks.nix with prek, MegaLinter, treefmt-nix, cocogitto, Copier, direnv
Purpose: Standardized starting point for new projects with quality checks and a reproducible Nix env

Branch naming strategy

Since many people will be contributing to this repository, we use a branching strategy that allows for parallel development while keeping the main branch stable.

Use the following branching strategy:

<human first name>/<work type>/<work name>

For example:

john/feat/add-packages
jane/fix/ui-bugs
joy/refactor/payment

<human first name> - will be derived from git config user.name or the author's first name. Ask the author for their first name if it's not available. <work type> - the type of work being done (e.g., feat, fix, refactor). Should match commit types from conventional commits. <work name> - the name of the work being done (e.g., add-packages, ui-bugs, payment)

General Guidelines

Communication

Explain what you're doing and why before making changes
Ask for clarification when requirements are ambiguous
Provide context for decisions, especially when multiple approaches exist

Code Quality

Follow existing code style and conventions in the project
Run linters and formatters before committing changes
Ensure all changes pass pre-commit hooks

File Operations

Always check if a file exists before attempting to modify it
Use appropriate tools to search for files rather than guessing paths
Preserve file formatting and structure unless explicitly asked to change it

AI Usage and Transparency

IMPORTANT: This project maintains full transparency about AI assistance.

AI Assistance Guidelines

AI can help with:

Boilerplate code and scaffolding
Documentation and comments
Test cases and test data
Refactoring suggestions
Bug fixes and debugging
Code review and optimization suggestions
Research and best practices

Human must:

Review all AI-generated code thoroughly
Test all functionality comprehensively
Make final decisions on architecture and approach
Approve all changes before committing
Understand the code (never commit code you don't understand)

Always:

Validate AI suggestions against project architecture (if such a document is present)
Follow best coding practices and idioms
Ensure code passes all tests and linters
Document every action in .agents/logs/ as described above

Never:

Skip testing because "AI wrote it"
Forget to write the log entry
Rely solely on AI for architectural decisions

Dev Environment

Enter the env with direnv (.envrc uses use flake and watches nix/) or nix develop
Prefer Blueprint args in Nix files: flake (shorthand for inputs.self), perSystem, pkgs, system
Consume same-flake packages via perSystem.self.<name> (e.g. perSystem.self.formatter.check) instead of path-importing Blueprint-loaded files
Flake layout lives under nix/ (formatter.nix, devshell.nix, checks/, modules/)
Use --help or a help subcommand before asking the user for tool details

Linting and Formatting

MegaLinter

Configuration is in .mega-linter.yml
Run locally with: bunx mega-linter-runner
Check reports in megalinter-reports/ directory
Not all linters need to pass — some are informational

CSpell (Spell Checking)

Configuration is in .config/cspell.json
Add project-specific words to the words array
Don't disable spell checking without good reason
Both file content and commit messages are spell-checked

treefmt / `nix fmt`

Format with nix fmt (Blueprint + treefmt-nix wrapper from nix/formatter.nix)
Verify with nix flake check (includes the formatting check)
Config modules live under nix/modules/tools/treefmt.nix (plus imported pedantix/smt modules)

Commit Messages

Format

Follow Conventional Commits format: <type>(<scope>): <description> as given here - https://www.conventionalcommits.org/en/v1.0.0/
Valid types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
For valid scopes, refer to the scopes array in cog.toml — it is the source of truth.

Examples

feat(precommit): add spell checking to commit messages
fix(cspell): resolve configuration issue
docs: update AGENTS.md with guidelines
chore(cspell): add technical terms to dictionary

Troubleshooting

Common Issues

Pre-commit hooks failing on commit:

Read the error message — it usually points directly to the fix
Try to fix the issue and retry the commit; do not skip hooks
Fix formatting with nix fmt first, then spell checking and linting
Hooks are managed via git-hooks.nix / prek (see nix/checks/pre-commit-check.nix)

Spell check failures:

Add legitimate technical terms to .config/cspell.json words array
Use proper capitalization for proper nouns
Don't add obvious typos to the dictionary

Template / Copier issues:

Ensure template syntax is valid before committing
Check for missing closing tags or brackets
Test template rendering if applicable (copier copy / copier update)

Missing skills or MCP tools:

Run apm install or uvx --from apm-cli apm install, then reload the agent

Getting Help

Review existing configuration files for examples
Blueprint folder layout: https://numtide.github.io/blueprint/main/getting-started/folder_structure/

Best Practices

Before Making Changes

Understand the current state of the project
Check if similar functionality already exists
Review relevant configuration files
Consider impact on users who will use this template

When Adding Dependencies

Prefer tools that don't require heavy installation
Document installation steps clearly
Consider cross-platform compatibility
Update relevant configuration files (flake inputs, apm.yml, Copier excludes as needed)

Testing Changes

Verify the project structure is correct
Prefer nix flake check where Nix is involved
Test on a clean environment if possible
Ensure documentation is updated

Project specific instructions will be documented here.

Project Context

Project Name: Profile Pulse
Project Type: Desktop contact management application with social media integration
Language: Rust
GUI Framework: Iced (pure Rust)
Database: SQLite with SQLx
License: GPLv3-or-later
Status: Planning phase (no code implementation yet)

Project Documentation

Before making changes, review the comprehensive documentation in the docs/ directory:

docs/PLAN.md - Technology stack, architecture decisions, and implementation strategy
docs/ARCHITECTURE.md - System architecture, data models, and design patterns
docs/ROADMAP.md - Development phases, tasks, and milestones
docs/API_INTEGRATION.md - Social media platform integration guides
docs/DEVELOPMENT.md - Development setup, testing, and contribution guidelines

General Guidelines

Communication

Explain what you're doing and why before making changes
Ask for clarification when requirements are ambiguous
Provide context for decisions, especially when multiple approaches exist
Reference relevant documentation when making architectural decisions

Code Quality

Follow existing code style and conventions in the project
Run linters and formatters before committing changes
Ensure all changes pass pre-commit hooks
Write tests for new functionality
Follow Rust best practices and idioms

File Operations

Always check if a file exists before attempting to modify it
Use appropriate tools to search for files rather than guessing paths
Preserve file formatting and structure unless explicitly asked to change it

Rust-Specific Guidelines

Code Style

Follow rustfmt formatting (run cargo fmt)
Address all clippy warnings (run cargo clippy)
Use meaningful variable and function names (snake_case)
Type names in PascalCase, constants in SCREAMING_SNAKE_CASE
Document public APIs with doc comments (///)

Architecture Principles

Refer to docs/ARCHITECTURE.md for:
- Layered architecture (UI, Business Logic, Service, Data Access)
- Design patterns (Repository, Trait Objects, Builder, Strategy)
- Error handling strategy (thiserror + anyhow)
- Security considerations

Dependencies

Check docs/PLAN.md for approved crates
New dependencies should align with project architecture
Justify dependency additions with specific use cases
Consider alternatives and trade-offs

Development Workflow

Before Starting Work

Review the ROADMAP.md to understand current phase
Check ARCHITECTURE.md for design patterns
Review DEVELOPMENT.md for setup instructions
Understand the module structure and responsibilities

AI-Assisted Work Documentation

IMPORTANT: This project maintains full transparency about AI assistance through work logs.

All AI-assisted work must be documented in .ai/logs/YYYY-MM-DD.md files:

Naming format: YYYY-MM-DD.md (e.g., 2024-12-15.md)
Multiple sessions per day: Append to the existing log file with timestamps
Generate timestamps: Use date --iso-8601=seconds or date '+%Y-%m-%d %H:%M:%S'

Each log entry must include:

Timestamp - When the work was performed
Request/Prompt - What initiated the work (user request or task description)
AI Model - Model name and version (e.g., Claude Sonnet 4.5, GPT-4, etc.)
Provider - AI provider (e.g., Anthropic, OpenAI)
Work Performed - Detailed description of what was done
Files Changed - List of files created/modified with line counts
Nature of Assistance - Type of help (code generation, documentation, refactoring, debugging, etc.)
Human Involvement - What decisions were made by humans, how output was reviewed/tested/modified, what was rejected or changed
Testing Status - Whether code was tested, compilation status, test results

Example log entry format:

## 2024-12-15 14:30:22+00:00

### Prompt

> Implement GitHub profile fetcher with rate limiting

### Request

User asked to implement GitHub profile fetcher with rate limiting

### AI Model

**Model**: Claude Sonnet 4.5
**Provider**: Anthropic

### Work Performed

- Implemented GitHubFetcher struct with async trait
- Added rate limiting using governor crate
- Created comprehensive error handling
- Added unit tests and integration tests

### Files Changed

- `src/social/github.rs` (created, ~250 lines)
- `tests/integration/github_tests.rs` (created, ~80 lines)
- `Cargo.toml` (modified, added governor dependency)

### Nature of Assistance

- Code generation for fetcher implementation
- Test case generation
- Error handling patterns

### Human Involvement

- Reviewed all generated code for correctness
- Modified rate limiting to be more conservative (5 req/min instead of 10)
- Added additional error cases not covered by AI
- Tested with real GitHub API
- Approved final implementation after modifications

### Testing Status

- ✅ Compiled successfully
- ✅ All 12 unit tests passing
- ✅ Integration tests passing with mock API
- ⏳ Manual testing with real API pending

Additional Materials: Place any other relevant documents (prompts, examples, references, generated docs) in the .ai folder

Commit Message Format: Reference the work log in commit messages:

feat(social): implement GitHub profile fetcher

AI-assisted implementation reviewed and tested.
See .ai/logs/2024-12-15.md for details.

Dev Environment Tips

Development Process

Use --help or help subcommand to get help on a command. It can even reveal hints on how to proceed ahead or optimize the number of steps.
Check tool documentation before asking the user for configuration details

# Format code
cargo fmt

# Check for errors
cargo check

# Run linter
cargo clippy

# Run tests
cargo test

# Run all pre-commit hooks
prek --all-files

Testing

Write unit tests in the same file as the code (#[cfg(test)] mod tests)
Write integration tests in tests/ directory
Use #[tokio::test] for async tests
Mock external APIs using mockito
Test database operations with SQLx test features

Pre-commit Hooks (prek)

Installation

Install with uv tool install prek and run checks via prek --all-files
Enable the hooks with prek install --install-hooks so they run automatically on each commit

Working with Hooks

If a pre-commit hook fails, read the error message carefully - it often suggests the fix
Run prek --all-files before committing to catch issues early
Some hooks auto-fix issues (like formatters); others require manual intervention