# AGENT_WORKFLOW.md

AI Agent Operational Workflow

This document defines the deterministic workflow that AI agents must follow when performing work in this repository.

The workflow ensures:

- predictable development cycles
- traceable decisions
- minimal risk of unintended changes
- consistent logging of AI actions

This file complements:

- `AGENT.md`
- `instructions-agent.md`
- `docs/ai-worklog.md`
- `docs/ai-prompts.md`
- `docs/ai-execution-log.md`

---

# Standard Workflow

Every AI task must follow this sequence:

PLAN → REVIEW → BUILD → VALIDATE → LOG

---

# Execution Order (Strict)

The following operational order must be respected when executing any BUILD task.

1. Implement changes (BUILD)
2. Run validation
   make fix
   make quality
3. Update AI logs
   - docs/ai-execution-log.md
   - docs/ai-prompts.md
   - docs/ai-worklog.md
4. Stage all modified files including logs
5. Create commit
6. Push only if explicitly requested

Important rule:
Logs must always be written **before creating a commit**. If log files are modified after a commit, the task is considered incomplete and must be corrected.

---

This sequence must not be skipped.

---

# 1. PLAN

Goal:
Understand the problem and determine the minimal solution.

Actions:

- inspect repository state
- read relevant source files
- analyze existing architecture
- identify root cause of the problem
- propose a minimal change

Rules:

- PLAN must **not modify code**
- PLAN must **not change files**
- PLAN must only produce analysis and a proposal

Output should include:

- diagnosis summary
- proposed changes
- expected file scope

---

# 2. REVIEW

Goal:
Validate the plan before implementing it.

Actions:

- confirm the proposed scope is minimal
- ensure no unrelated components are affected
- verify the change aligns with project architecture

Rules:

- If the scope expands unexpectedly, return to PLAN.

---

# 3. BUILD

Goal:
Implement the approved change.

Actions:

- modify only the files defined in scope
- preserve existing architecture
- avoid unnecessary refactors
- maintain compatibility with existing behavior

BUILD tasks may modify:

- source files
- tests
- documentation

BUILD tasks must remain minimal and targeted.

---

# 4. VALIDATE

Goal:
Ensure the repository remains stable.

Agents must run:

```
make fix
make quality
```

Validation must pass before changes are considered complete.

---

# 5. LOG

Goal:
Record the AI activity for traceability.

Three log files must be updated.

### Work Log

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

Record:

- AI BUILD ENTRY
- or AI PLAN ENTRY

Including:

- 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

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

Record:

- Date (YYYY-MM-DD HH:MM)
- Task ID
- Agent
- Task
- prompt summary
- scope
- result summary

Do not store chain-of-thought reasoning.

### Execution Log

```
docs/ai-execution-log.md
```

Record the full visible execution trace including:

- Date (YYYY-MM-DD HH:MM)
- Task ID
- Agent
- Task Type
- Full prompt text
- Agent todos
- Execution report

The execution log preserves the complete operational record of the AI session.

---

# Task ID Coordination

Every PLAN or BUILD must generate a unique Task ID.

Format:

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

Example:

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

The same Task ID must appear in:

- ai-execution-log.md
- ai-prompts.md
- ai-worklog.md

---

# Commit Workflow

Agents must **not commit or push automatically** unless explicitly instructed.

Before creating a commit the agent must ensure:

- validation has passed
- AI logs have been written
- docs/ai-execution-log.md, docs/ai-worklog.md and docs/ai-prompts.md are staged

Commits that omit required AI log entries violate the repository workflow rules.

When commits are requested:

1. Validate repository state
2. Stage modified files
3. Use structured commit messages

Example:

```
feat: improve terminal navigation

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

Documentation-only updates should use:

```
docs:
```

---

# Failure Handling

If validation fails:

Agents must:

1. stop the BUILD process
2. report the error
3. propose a fix

Agents must **not silently bypass failing checks**.

---

# Scope Control

Agents must strictly respect the defined scope.

If additional changes appear necessary:

- return to PLAN
- propose a new change

Do not expand scope during BUILD.

---

# End of Document