# AGENTS.md

Instructions for Codex and other AI contributors working on Iris.

## Operating Mode

- Read the relevant files before editing.
- Keep changes scoped to the request and the current project phase.
- Do not overwrite user changes or unrelated work.
- Prefer existing project patterns once source files are added.
- Use ASCII text unless a file already uses another character set.
- Run `./scripts/check_repo.sh` before committing.
- When a real tech stack exists, also run the stack-specific formatter, linter,
  and tests.

## Project Context

- Project name: Iris.
- Repository owner: `khaledyusuf44`.
- Core AI contributor: Codex.
- Current phase: Day 1 constraint-engine validation.
- Implementation stack: Python validation engine now; Gradio UI later.
- Source files: `iris/` package. Local task prompts stay untracked.

## Expected Workflow

1. Check `git status --short --branch`.
2. Read `README.md`, `CONTRIBUTING.md`, and relevant files in `docs/`.
3. Make the smallest useful change that moves the project forward.
4. Add or update tests when behavior changes.
5. Update `docs/CODEX_LOG.md` for substantive work.
6. Run repository checks.
7. Commit only intentional files.

## Codex Logging

For each substantive Codex change, add a short entry to `docs/CODEX_LOG.md` with:

- Date.
- Commit hash, once available.
- What changed.
- Validation or test result.
- Whether the Iris quality gate passed or failed.

Do not put secrets, private prompts, local-only handoff notes, or raw API keys in
the Codex log.

## Source File Intake

When source files arrive:

- Identify the framework, package manager, runtime, and build commands.
- Move files into the stack's normal structure.
- Add install, run, test, and build commands to `README.md`.
- Update `docs/ARCHITECTURE.md` with the actual modules and data flow.
- Add CI around real project checks.
- Keep secrets in local environment files, not committed files.

## Iris Product Rule

The model applies pressure; it does not solve the user's idea. Any output that
becomes a finished idea, plan, or generic advice is a product bug.

## Commit Style

Use short imperative commit messages, for example:

```text
Bootstrap project structure
Add initial app shell
Wire API client tests
```