cd-browser/AGENT.md

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

---