cleanup: remove AI internal files for public repo focus

- Removed AGENT.md, AGENT_WORKFLOW.md, AI_TASK_TEMPLATE.md, instructions-agent.md - These were internal AI development tools, not needed for end-users - Repository now cleaner and more product-focused - Files can be recovered from git history if needed for future development
2026-04-02 16:48:58 +02:00
parent f28fef7758
commit 10c3849fb3
4 changed files with 0 additions and 966 deletions
--- a/AGENT.md
+++ b/AGENT.md
@@ -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
 ---
--- a/AGENT_WORKFLOW.md
+++ b/AGENT_WORKFLOW.md
@@ -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
--- a/AI_TASK_TEMPLATE.md
+++ b/AI_TASK_TEMPLATE.md
@@ -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.
--- a/instructions-agent.md
+++ b/instructions-agent.md
@@ -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.