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
This commit is contained in:
260
AGENT.md
260
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
|
||||
---
|
||||
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user