feat: introduce AI agent framework and task tooling

- 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

AGENT_WORKFLOW.md

@@ -0,0 +1,249 @@
+
+
+# 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