# 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 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 ""` 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 ""` 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: ```bash 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.