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

@@ -0,0 +1,260 @@
+# AGENT.md
+
+AI Agent Development Guide
+
+This file defines the operational rules that AI agents must follow when working in this repository.
+
+The goal is to ensure:
+- reproducible AI-assisted development
+- traceable decisions
+- consistent repository history
+- safe automated contributions
+
+This document complements:
+- `instructions-agent.md`
+- `docs/ai-worklog.md`
+- `docs/ai-prompts.md`
+
+---
+
+# Core Principles
+
+Agents must prioritize:
+
+1. Deterministic changes
+2. Minimal scope modifications
+3. Explicit logging of work
+4. Repository stability
+
+Agents must never:
+
+- fabricate repository state
+- invent files that do not exist
+- modify unrelated parts of the project
+- skip validation steps
+
+---
+
+# Development Workflow
+
+Agents operate using two primary task types:
+
+## PLAN
+
+Used to:
+- investigate problems
+- inspect repository state
+- propose architecture changes
+
+PLAN tasks must:
+- analyze the current implementation
+- identify the root cause
+- propose minimal changes
+
+PLAN tasks **must not modify code**.
+
+---
+
+## BUILD
+
+Used to:
+- implement changes
+- update code
+- add tests
+- update documentation
+
+BUILD tasks may:
+- modify source files
+- update tests
+- update documentation
+
+BUILD tasks must:
+- remain minimal in scope
+- preserve existing behavior unless explicitly changed
+
+---
+
+# Validation Requirements
+
+All BUILD tasks must run:
+
+```
+make fix
+make quality
+```
+
+These commands must pass before changes are considered valid.
+
+---
+
+# Logging System
+
+All significant AI actions must be recorded.
+
+Two log files are used:
+
+```
+docs/ai-worklog.md
+docs/ai-prompts.md
+```
+
+---
+
+# Worklog Entries
+
+Executed work must be recorded in:
+
+```
+docs/ai-worklog.md
+```
+
+Each entry must follow the standard format defined in `instructions-agent.md`.
+
+Mandatory fields:
+
+- 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
+
+Prompts that trigger significant work must be recorded in:
+
+```
+docs/ai-prompts.md
+```
+
+Each prompt entry must include:
+
+- Date
+- Task ID
+- Agent
+- Task
+- Scope
+- Prompt Summary
+- Result Summary
+
+Chain-of-thought reasoning must **never be stored**.
+
+---
+
+# Task IDs
+
+All tasks must include a unique identifier.
+
+Format:
+
+```
+BUILD-YYYYMMDD-XXX
+PLAN-YYYYMMDD-XXX
+```
+
+Examples:
+
+```
+BUILD-20260315-001
+PLAN-20260316-002
+```
+
+This allows prompts and worklog entries to be correlated.
+
+---
+
+# Git Rules
+
+Agents must follow these repository rules.
+
+Agents must **not commit or push** unless explicitly requested.
+
+When committing:
+
+Use structured commit messages.
+
+Example:
+
+```
+feat: improve terminal navigation behavior
+
+- refine tree navigation
+- improve scrolling continuity
+- update AI logs
+```
+
+Documentation-only updates should use:
+
+```
+docs:
+```
+
+---
+
+# Code Modification Rules
+
+Agents should prefer:
+
+- small targeted patches
+- isolated logic changes
+- preserving existing abstractions
+
+Agents should avoid:
+
+- rewriting entire modules
+- introducing unnecessary dependencies
+- altering unrelated code paths
+
+---
+
+# UI Changes
+
+When modifying UI behavior:
+
+- keep navigation predictable
+- preserve keyboard ergonomics
+- ensure selections remain visible
+- maintain compatibility with history mode
+
+---
+
+# Testing Rules
+
+Whenever logic changes:
+
+- update existing tests
+- add focused tests when appropriate
+
+Tests should validate behavior, not implementation details.
+
+---
+
+# Scope Discipline
+
+Agents must strictly respect scope defined in prompts.
+
+If additional changes appear necessary:
+
+Agents must propose them in a PLAN task before implementing.
+
+---
+
+# Repository Safety
+
+Agents must not:
+
+- delete important files
+- alter project configuration without justification
+- introduce breaking changes without explicit instruction
+
+---
+
+# End of Document
+---

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

AI_TASK_TEMPLATE.md

@@ -0,0 +1,145 @@
+# AI Task Template
+
+Reusable prompt template for launching tasks with AI agents.
+
+This template enforces the repository workflow defined in:
+
+- AGENT.md
+- AGENT_WORKFLOW.md
+- instructions-agent.md
+
+It ensures every task follows the deterministic sequence:
+
+PLAN → REVIEW → BUILD → VALIDATE → LOG
+
+---
+
+# Basic Task Structure
+
+Use the following structure when requesting work from an AI agent.
+
+```
+Task Type:
+PLAN | BUILD
+
+Task ID:
+PLAN-YYYYMMDD-XXX | BUILD-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Short description of the goal.
+
+Context:
+Relevant background about the current repository state.
+
+Scope:
+List of files or directories the agent may modify or inspect.
+
+Requirements:
+Detailed description of the behavior that must be implemented or analyzed.
+
+Constraints:
+Things the agent must NOT change or must preserve.
+
+Testing:
+Describe expected tests or validations.
+
+Validation:
+The agent must run:
+
+make fix
+make quality
+
+Logging requirements:
+- Append an entry to docs/ai-worklog.md
+- Append an entry to docs/ai-prompts.md
+- Include Date, Task ID, Agent, Scope, Result
+
+Git requirements:
+- Do NOT commit or push unless explicitly requested.
+
+Expected Report:
+The agent must summarize:
+- files changed
+- behavior changes
+- validation results
+```
+
+---
+
+# Example BUILD Task
+
+```
+Task Type:
+BUILD
+
+Task ID:
+BUILD-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Improve vertical scrolling behavior in the terminal UI.
+
+Scope:
+- src/app/ui.py
+- tests/test_ui.py
+
+Requirements:
+Ensure the selected entry remains visible when navigating through long directory lists.
+
+Constraints:
+Do not modify navigator logic.
+
+Testing:
+Add helper tests if necessary.
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+Update ai-worklog.md and ai-prompts.md using the standard log format.
+```
+
+---
+
+# Example PLAN Task
+
+```
+Task Type:
+PLAN
+
+Task ID:
+PLAN-YYYYMMDD-XXX
+
+Date:
+YYYY-MM-DD HH:MM
+
+Objective:
+Investigate inconsistent navigation behavior.
+
+Scope:
+- src/app/ui.py
+- src/app/navigator.py
+
+Requirements:
+Analyze the current navigation flow and propose a minimal fix.
+
+Constraints:
+Do not modify code.
+
+Expected Output:
+- diagnosis summary
+- proposed changes
+- expected file scope
+```
+
+---
+
+# Notes
+
+This template keeps AI interactions consistent across tasks and helps maintain a clean development history.

scripts/ai-task

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+
+# ai-task
+# Helper CLI to generate AI task prompts based on AI_TASK_TEMPLATE.md
+# Usage:
+#   scripts/ai-task build "Objective text" [scope...]
+#   scripts/ai-task plan "Objective text" [scope...]
+
+set -e
+
+TYPE="$1"
+OBJECTIVE="$2"
+shift 2 || true
+SCOPE=("$@")
+
+if [[ -z "$TYPE" || -z "$OBJECTIVE" ]]; then
+  echo "Usage: ai-task <plan|build> \"Objective\" [scope files...]"
+  exit 1
+fi
+
+TYPE_LOWER=$(echo "$TYPE" | tr '[:upper:]' '[:lower:]')
+TYPE_UPPER=$(echo "$TYPE_LOWER" | tr '[:lower:]' '[:upper:]')
+
+DATE=$(date "+%Y-%m-%d %H:%M")
+DAY=$(date "+%Y%m%d")
+
+case "$TYPE_LOWER" in
+  build)
+    PREFIX="BUILD"
+    ;;
+  plan)
+    PREFIX="PLAN"
+    ;;
+  *)
+    echo "Error: task type must be 'plan' or 'build'"
+    exit 1
+    ;;
+esac
+
+WORKLOG_FILE="docs/ai-worklog.md"
+LAST_SEQ=0
+
+if [[ -f "$WORKLOG_FILE" ]]; then
+  LAST_MATCH=$(grep -Eo "${PREFIX}-${DAY}-[0-9]{3}" "$WORKLOG_FILE" | tail -n 1 || true)
+  if [[ -n "$LAST_MATCH" ]]; then
+    LAST_SEQ=${LAST_MATCH##*-}
+    LAST_SEQ=$((10#$LAST_SEQ))
+  fi
+fi
+
+NEXT_SEQ=$(printf "%03d" $((LAST_SEQ + 1)))
+TASK_ID="${PREFIX}-${DAY}-${NEXT_SEQ}"
+
+# Build scope block
+cat <<EOF
+Task Type:
+${TYPE_UPPER}
+
+Task ID:
+${TASK_ID}
+
+Date:
+${DATE}
+
+Objective:
+${OBJECTIVE}
+
+Context:
+<describe repository state if needed>
+
+Scope:
+EOF
+
+if [ ${#SCOPE[@]} -gt 0 ]; then
+  for item in "${SCOPE[@]}"; do
+    printf '%s\n' "- ${item}"
+  done
+else
+  printf '%s\n' "- <fill scope>"
+fi
+
+cat <<EOF
+
+Requirements:
+<describe expected behavior>
+
+Constraints:
+- follow AGENT_WORKFLOW.md
+- keep scope minimal
+- preserve existing behavior unless explicitly changed
+
+Testing:
+<describe expected tests>
+
+Validation:
+make fix
+make quality
+
+Logging requirements:
+- append entry to docs/ai-worklog.md
+- append entry to docs/ai-prompts.md
+- include Date, Task ID, Agent, Scope
+- use Task ID: ${TASK_ID}
+
+Git requirements:
+- do NOT commit or push unless explicitly requested
+
+Expected Report:
+- files changed
+- behavior changes
+- validation results
+EOF