# AGENT.md

AI Agent Development Guide

This file defines the operational rules that AI agents must follow when working in this repository.

The goal is to ensure:
- reproducible AI-assisted development
- traceable decisions
- consistent repository history
- safe automated contributions

This document complements:
- `instructions-agent.md`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`

---

# Core Principles

Agents must prioritize:

1. Deterministic changes
2. Minimal scope modifications
3. Explicit logging of work
4. Repository stability

Agents must never:

- fabricate repository state
- invent files that do not exist
- modify unrelated parts of the project
- skip validation steps

---

# Development Workflow

Agents operate using two primary task types:

## PLAN

Used to:
- investigate problems
- inspect repository state
- propose architecture changes

PLAN tasks must:
- analyze the current implementation
- identify the root cause
- propose minimal changes

PLAN tasks **must not modify code**.

---

## BUILD

Used to:
- implement changes
- update code
- add tests
- update documentation

BUILD tasks may:
- modify source files
- update tests
- update documentation

BUILD tasks must:
- remain minimal in scope
- preserve existing behavior unless explicitly changed

---

# Validation Requirements

All BUILD tasks must run:

```
make fix
make quality
```

These commands must pass before changes are considered valid.

---

# Logging System

All significant AI actions must be recorded.

Two log files are used:

```
docs/ai-worklog.md
docs/ai-prompts.md
```

---

# Worklog Entries

Executed work must be recorded in:

```
docs/ai-worklog.md
```

Each entry must follow the standard format defined in `instructions-agent.md`.

Mandatory fields:

- Date (YYYY-MM-DD HH:MM)
- Task ID
- Agent
- Task
- Objective
- Scope
- Files Modified / Files Inspected
- Key Decisions / Proposed Changes
- Validation
- Result
- Open Issues

---

# Prompt Log

Prompts that trigger significant work must be recorded in:

```
docs/ai-prompts.md
```

Each prompt entry must include:

- Date
- Task ID
- Agent
- Task
- Scope
- Prompt Summary
- Result Summary

Chain-of-thought reasoning must **never be stored**.

---

# Task IDs

All tasks must include a unique identifier.

Format:

```
BUILD-YYYYMMDD-XXX
PLAN-YYYYMMDD-XXX
```

Examples:

```
BUILD-20260315-001
PLAN-20260316-002
```

This allows prompts and worklog entries to be correlated.

---

# Git Rules

Agents must follow these repository rules.

Agents must **not commit or push** unless explicitly requested.

When committing:

Use structured commit messages.

Example:

```
feat: improve terminal navigation behavior

- refine tree navigation
- improve scrolling continuity
- update AI logs
```

Documentation-only updates should use:

```
docs:
```

---

# Code Modification Rules

Agents should prefer:

- small targeted patches
- isolated logic changes
- preserving existing abstractions

Agents should avoid:

- rewriting entire modules
- introducing unnecessary dependencies
- altering unrelated code paths

---

# UI Changes

When modifying UI behavior:

- keep navigation predictable
- preserve keyboard ergonomics
- ensure selections remain visible
- maintain compatibility with history mode

---

# Testing Rules

Whenever logic changes:

- update existing tests
- add focused tests when appropriate

Tests should validate behavior, not implementation details.

---

# Scope Discipline

Agents must strictly respect scope defined in prompts.

If additional changes appear necessary:

Agents must propose them in a PLAN task before implementing.

---

# Repository Safety

Agents must not:

- delete important files
- alter project configuration without justification
- introduce breaking changes without explicit instruction

---

# End of Document
---