cd-browser/instructions-agent.md

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