Saky
e766210920
- add AGENT.md describing the agent system - add AGENT_WORKFLOW.md defining the execution workflow - add AI_TASK_TEMPLATE.md for structured task prompts - add scripts/ai-task CLI tool for generating standardized agent tasks
261 lines
3.7 KiB
Markdown
261 lines
3.7 KiB
Markdown
# 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
|
|
---
|