saky/cd-browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: introduce AI agent framework and task tooling

Browse Source 
- 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
This commit is contained in:
Saky
2026-03-16 01:38:36 +01:00
parent 6849631cc1
commit e766210920
4 changed files with 766 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

260
AGENT.md Normal file
View File

@@ -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
---

249
AGENT_WORKFLOW.md Normal file
View File

@@ -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

145
AI_TASK_TEMPLATE.md Normal file
View File

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

112
scripts/ai-task Executable file
View File

@@ -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