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