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
250 lines
3.3 KiB
Markdown
250 lines
3.3 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
|
|
|
|
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
|