cd-browser/AGENT_WORKFLOW.md

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

---

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-worklog.md
   • docs/ai-prompts.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.

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.

Before creating a commit the agent must ensure:

• validation has passed
• AI logs have been written
• 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