Saky
9704d3ef5b
- strengthen agent workflow rules and commit/log ordering - improve AI logging instructions and traceability - add agent framework documents and task generation tooling - keep repository workflow consistent for future AI-assisted tasks
280 lines
4.1 KiB
Markdown
280 lines
4.1 KiB
Markdown
|
|
|
|
# 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
|