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

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`

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. Logging is part of the task itself and must not be skipped.
5. The task is not complete until the logs are updated.

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.

## 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  
Task: build  
Objective: short description of the task

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  
Task: plan  
Objective: short description of planning objective

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