# 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`

---

# Standard Workflow

Every AI task must follow this sequence:

PLAN → REVIEW → BUILD → VALIDATE → LOG

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.

Two 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.

---

# 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-prompts.md
- ai-worklog.md

---

# Commit Workflow

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

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