photoanalyzer/AGENTS.md

Agent Instructions — Photo Analyzer

INTEGRATED_PIPELINE_CONCEPT.md is the authoritative product and architecture foundation for every user story. Before claiming or resuming implementation, read it in full, then use it to interpret the story's scope, acceptance criteria, donor strategy, architecture boundaries, safety invariants, fixture requirements, and test obligations. Read CLAUDE.md as operational donor context after the concept. If an issue, backlog Markdown file, or implementation idea conflicts with the concept, do not silently follow the conflicting source: preserve the concept and stop for an explicit decision when the conflict materially changes scope or behavior.

Re-read the complete concept whenever context has been compacted/lost, the concept has changed since the story began, or an implementation session is resumed without a reliable record that the current version was read. A summary, prior familiarity, or reading only the story's phase is not sufficient.

Preserve the established project invariants: never inspect or process content beneath any _IGNORE/ directory; write verified EXIF before Immich upload; use managed immich-go uploads rather than External Libraries; keep operations resume-safe; and treat the existing CLI implementations as primary donors rather than rewriting them.

Work-item helper

The reusable workflow helper is a self-contained subproject under work_item/:

• launcher: work_item/scripts/work-item;
• Python wrapper: work_item/scripts/python;
• active project configuration: work_item/.work-item.yml;
• implementation: work_item/src/work_item/;
• helper tests: work_item/tests/;
• complete usage and configuration reference: work_item/README.md.

Do not recreate root-level scripts/, tests/, or .work-item.* files for the helper. Its launcher adds work_item/src/ to PYTHONPATH and selects Conda base when it provides Python 3.12 or newer, with supported system Python as fallback.

The helper supports TOML, YAML, dotenv, and WORK_ITEM_* environment overrides. This repository intentionally keeps its configuration inside work_item/.work-item.yml. Do not change its repository identity, required tests, allow list, deny list, size limit, or CI policy merely to bypass a workflow failure.

Story stage is tracked by status/* labels and issue open/close, which serve as the board; work-item does not move cards between Gitea project-board columns (Gitea's API cannot move cards). Use label-filtered issue views instead — see work_item/README.md → "Kanban / project board position".

Workflow state is local at .git/work-item-state.json and must never be committed. claim is resume-aware:

• with no active state, it selects the lowest-numbered eligible story whose Gitea dependencies are closed, updates main, creates the feature branch, assigns the issue, and applies status/in-progress;
• on the active story branch, rerunning it preserves and resumes dirty implementation work;
• from another clean branch, rerunning it switches back to the claimed branch;
• for a blocked story, rerunning it explicitly returns that same story to status/in-progress instead of selecting a later story;
• a story already in review cannot be replaced by another claim.

submit always combines configured required tests with repeated story-specific --test arguments and runs duplicate commands only once. It checks denied/allowed paths, maximum file size, likely credentials/private keys, and Git whitespace errors before allowing a commit. The first invocation without --yes is a mandatory review step; only the confirmed invocation may stage, commit, push, open/reuse a pull request, record test evidence, and move the issue to review. If push or PR-related remote work partially succeeds, rerun the same command so its recovery logic can reuse the existing commit and pull request.

Mandatory implementation workflow

When asked to start, resume, or continue implementation, work from this isolated Git repository and use work_item/scripts/work-item. Gitea issues and their dependencies are the authoritative backlog.

1. Read the current INTEGRATED_PIPELINE_CONCEPT.md completely and treat it as the foundation for all decisions in the story. Then read CLAUDE.md for operational donor context.
2. Run work_item/scripts/work-item claim.
3. Run work_item/scripts/work-item status when resuming or whenever branch/state is uncertain. Work only on the claimed story and its generated feature branch.
4. Read the entire issue, linked specification, dependencies, and acceptance criteria. Reconcile them with the concept before designing or changing code.
5. Inspect the legacy CLI donors — frozen in legacy_cli_archive/ since US07-01, with their ledger — before replacing applicable behavior. Update the donor ledger and characterization tests required by the story.
6. Implement every acceptance criterion and its automated tests.
7. Run story-specific tests and the accumulated regression suite required by the epic.
8. Run work_item/scripts/work-item submit --test "<story-specific command>" without --yes and review the reported diff and file list.
9. If the changes are correct and safe, rerun with --yes. This commits, pushes, opens a pull request, records test evidence, and moves the issue to review.
10. After review and successful CI, run work_item/scripts/work-item complete --merge. This verifies the merge, closes the issue, returns to updated main, and removes the local feature branch.
11. Continue with the next eligible story by returning to step 1.

If genuinely blocked, run work_item/scripts/work-item block --reason "<precise reason>" and stop. Never skip to a later story whose dependencies are open. Never mark work done when tests are missing, skipped, or failing.

Git and privacy safety

• Never run automated Git operations from the personal photo-library directory.
• Never stage or commit real photos, videos, _IGNORE/ content, databases, logs, credentials, environment files, caches, generated thumbnails, or runtime data.
• Never use force-push, destructive reset, untracked-file deletion, or automatic merge conflict resolution.
• Do not bypass work_item/scripts/work-item safety checks or manually close implementation issues to conceal a failed transition.
• Do not edit .git/work-item-state.json manually. Use claim, block, submit, and complete so local Git state and Gitea state remain consistent.
• Preserve unrelated user changes and stop if the working tree is unexpectedly dirty.

When modifying the helper itself, run all of its own checks from the repository root:

ruff check --no-cache work_item/src work_item/tests
ruff format --check --no-cache work_item/src work_item/tests
work_item/scripts/python -m unittest discover -s work_item/tests -v

Completion standard

A story is complete only when its pull request is merged, required automated tests and CI pass, test evidence is recorded on the issue, the issue is closed with status/done, and the local repository is back on a clean, current main branch.