105 lines
5.5 KiB
Markdown
105 lines
5.5 KiB
Markdown
# Agent Instructions — Photo Analyzer
|
|
|
|
Read `CLAUDE.md` and `INTEGRATED_PIPELINE_CONCEPT.md` before implementation. 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.
|
|
|
|
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. Run `work_item/scripts/work-item claim`.
|
|
2. 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.
|
|
3. Read the entire issue, linked specification, dependencies, and acceptance criteria.
|
|
4. Inspect the legacy CLI donors before replacing applicable behavior. Update the donor
|
|
ledger and characterization tests required by the story.
|
|
5. Implement every acceptance criterion and its automated tests.
|
|
6. Run story-specific tests and the accumulated regression suite required by the epic.
|
|
7. Run `work_item/scripts/work-item submit --test "<story-specific command>"` without
|
|
`--yes` and review the reported diff and file list.
|
|
8. 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.
|
|
9. 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.
|
|
10. 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:
|
|
|
|
```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.
|