diff --git a/AGENT.md b/AGENT.md deleted file mode 100644 index 6daa5c3..0000000 --- a/AGENT.md +++ /dev/null @@ -1,260 +0,0 @@ -# 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 ---- diff --git a/AGENT_WORKFLOW.md b/AGENT_WORKFLOW.md deleted file mode 100644 index 7515e35..0000000 --- a/AGENT_WORKFLOW.md +++ /dev/null @@ -1,298 +0,0 @@ -# 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` -- `docs/ai-execution-log.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-execution-log.md - - docs/ai-prompts.md - - docs/ai-worklog.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. - -Three 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. - -### Execution Log - -``` -docs/ai-execution-log.md -``` - -Record the full visible execution trace including: - -- Date (YYYY-MM-DD HH:MM) -- Task ID -- Agent -- Task Type -- Full prompt text -- Agent todos -- Execution report - -The execution log preserves the complete operational record of the AI session. - ---- - -# 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-execution-log.md -- 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-execution-log.md, 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 diff --git a/AI_TASK_TEMPLATE.md b/AI_TASK_TEMPLATE.md deleted file mode 100644 index b13b983..0000000 --- a/AI_TASK_TEMPLATE.md +++ /dev/null @@ -1,179 +0,0 @@ -# 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 -- Append an entry to docs/ai-execution-log.md -- Include Date, Task ID, Agent, Scope, Result - -Execution Logging requirements: -- Append an entry to docs/ai-execution-log.md -- Include: - - full prompt - - agent todos - - final execution report -- Use the standard execution log format defined in docs/ai-execution-log.md - -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 `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format. - -Execution Logging requirements: -- Update docs/ai-execution-log.md with: - - full prompt - - agent todos - - final execution report - -Git requirements: -- Do NOT commit or push unless explicitly requested. -``` - ---- - -# 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. - -Validation: -make fix -make quality - -Logging requirements: -- Update `docs/ai-worklog.md` and `docs/ai-prompts.md` using the standard log format. - -Execution Logging requirements: -- Update docs/ai-execution-log.md with: - - full prompt - - agent todos - - final execution report - -Git requirements: -- Do NOT commit or push unless explicitly requested. - -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. diff --git a/instructions-agent.md b/instructions-agent.md deleted file mode 100644 index 73aead1..0000000 --- a/instructions-agent.md +++ /dev/null @@ -1,229 +0,0 @@ -# Agent Instructions: Universal Python Project Template - -## Project Overview -This repository is a universal and adaptable Python template intended to serve as a professional starting point for new projects. - -## Core Directives -1. All code, comments, variables, string literals, commit messages, and documentation must be written in English. -2. Use Python 3.11+ with type hints whenever possible. -3. Follow clean code principles and PEP 8. -4. Keep modules small, cohesive, and maintainable. -5. Use consistent docstrings for public classes and functions. -6. Prefer explicit error handling over silent failures. - -## Architecture Guidelines -1. Keep business logic separate from infrastructure concerns. -2. Avoid mixing configuration, I/O, and domain logic in the same module. -3. Prefer reusable services over duplicated logic. -4. Do not introduce unnecessary complexity or premature abstractions. - -## Quality Standards -1. Every meaningful feature should include tests. -2. Run formatting, linting, and type checks before considering a task complete. -3. Keep the README updated whenever setup, commands, or structure changes. -4. Do not leave placeholder code unless clearly marked. - -## Tooling -- Testing: pytest -- Formatting: black -- Linting: ruff -- Static typing: mypy - -## Expected Project Structure -src/app/ -tests/ -scripts/ -README.md -instructions-agent.md -pyproject.toml - -## Agent Workflow -1. First understand the repository structure. -2. Propose a short implementation plan before major changes. -3. Reuse existing modules whenever possible. -4. Keep changes minimal, coherent, and production-oriented. -5. Validate changes with tests and quality tools when possible. - -## Application Specification - -This repository includes an application specification that defines the expected behavior of the project. - -Primary specification file: - -- `specs/cd_browser_spec.md` - -Agent rules: - -1. Before implementing any feature, read the application specification. -2. If implementation details are unclear, follow the specification first. -3. If the specification conflicts with a previous assumption, the specification takes precedence. -4. Keep implementation aligned with the MVP scope unless explicitly asked to extend it. -5. After code changes, run the appropriate validation workflow defined by this repository. - -## AI Worklog Policy - -This repository maintains an AI-assisted development log. - -Files: -- `docs/ai-worklog.md` -- `docs/ai-prompts.md` -- `docs/ai-execution-log.md` - -Rules: -1. After every significant `plan` or `build` task, append a concise worklog entry to `docs/ai-worklog.md`. -2. Each worklog entry must include: - - date - - task type (`plan` or `build`) - - short objective - - files inspected or modified - - key decisions - - validation commands run - - result - - unresolved issues if any -3. When a prompt meaningfully changes architecture, behavior, workflow, debugging direction, or project structure, append the prompt (or a concise cleaned version of it) to `docs/ai-prompts.md`. -4. Do not store private chain-of-thought or internal reasoning. -5. Store only concise, user-facing summaries of what was done. -6. Keep entries chronological and easy to scan. - -## Mandatory AI Logging - -Every significant AI interaction in this repository must be logged. - -This applies to: -- `plan` tasks -- `build` tasks -- debugging tasks -- documentation tasks -- architectural discussions that affect the project - -Required files: -- `docs/ai-worklog.md` -- `docs/ai-prompts.md` -- `docs/ai-execution-log.md` - -Mandatory rules: -1. After every significant `plan` task, append a concise entry to `docs/ai-worklog.md`. -2. After every significant `build` task, append a concise entry to `docs/ai-worklog.md`. -3. If the task was driven by a meaningful prompt, also append an entry to `docs/ai-prompts.md`. -4. The agent must append a full execution entry to `docs/ai-execution-log.md` including: - - the full prompt provided to the agent - - the agent todo list or execution plan - - the final execution report produced by the agent -5. Logging is part of the task itself and must not be skipped. -6. The task is not complete until the logs are updated. -7. Logs must always be written **before creating a commit**. -8. The agent must ensure that the following files are updated and staged before any commit: - - `docs/ai-worklog.md` - - `docs/ai-prompts.md` - - `docs/ai-execution-log.md` -9. If a commit is created without the corresponding log entries, the task is considered incomplete and must be corrected. -10. Log entries must be part of the same commit whenever possible to maintain traceability between the code change and the AI task that produced it. - -Each worklog entry must include: -- date -- task type (`plan` or `build`) -- short objective -- files inspected or modified -- key decisions -- validation commands run, if any -- result -- unresolved issues, if any - -Validation logging rule: -- If validation commands such as `make fix`, `make quality`, `pytest`, or other checks are executed during the task, the worklog entry must record them explicitly. -- The value `validation: not run` may only be used if no validation commands were executed. -- The worklog entry must reflect the actual commands run during the task. - - -Each prompt log entry must include: -- date -- task type (`plan` or `build`) -- short prompt summary -- scope -- result summary - -Rules: -- Do not store chain-of-thought or private reasoning. -- Store only concise user-facing summaries. -- Keep entries chronological. -- Even small but meaningful tasks must be logged. - -Execution log entries must include: -- date -- task ID -- task type (`plan` or `build`) -- full prompt text -- agent todos -- execution report - -## Standard AI Log Entry Format - -To ensure consistency and readability of long AI-assisted development histories, all log entries must follow a standardized block format. - -Agents must write log entries using the following structure. - -Example for build tasks: - -### AI BUILD ENTRY -Date: YYYY-MM-DD HH:MM -Task ID: BUILD-YYYYMMDD-XXX -Agent: OpenCode -Task: build -Objective: short description of the task - -Scope: -- src/app/module.py -- tests/test_module.py - -Files Modified: -- file/path/example.py -- another/file.md - -Key Decisions: -- short bullet explaining important choices - -Validation: -- make fix (passed) -- make quality (passed) - -Result: -- short description of what changed or was achieved - -Open Issues: -- optional list of unresolved problems - -Example for plan tasks: - -### AI PLAN ENTRY -Date: YYYY-MM-DD HH:MM -Task ID: PLAN-YYYYMMDD-XXX -Agent: OpenCode -Task: plan -Objective: short description of planning objective - -Scope: -- src/app/module.py -- specs/module_spec.md - -Files Inspected: -- src/app/example.py -- specs/example_spec.md - -Proposed Changes: -- summary of planned changes - -Notes: -- optional relevant observations - -Rules: -- Always use these headers exactly (`AI BUILD ENTRY` or `AI PLAN ENTRY`). -- Keep entries concise and structured. -- Do not include chain-of-thought reasoning. -- Use bullet points when possible. -- This format must be used when updating `docs/ai-worklog.md`. -- The Date field must include both date and time using the format YYYY-MM-DD HH:MM. -- Every log entry must include a `Task ID`. -- `Task ID` format must be `BUILD-YYYYMMDD-XXX` or `PLAN-YYYYMMDD-XXX`. -- `Agent` must identify the tool or AI system performing the task (e.g., OpenCode). -- `Scope` must describe the main files or project areas affected. -- These fields make the AI worklog suitable for long-term traceability and large histories.