Index & Describe an Image Set
Given a folder of images, produce a structured index that describes each one (caption, tags, notable content) in a consistent schema, then validates coverage and consistency. For cataloguing, search, or alt-text generation over an image collection.
Steps
Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.
- Scope the indexplannerentry
fields per image + output schema + criteria
Show working prompt
Decide the index schema before describing anything. The final output is workspace `index.json` with an `images` array; define fields per image (filename, caption, tags, dominantColors, orientation, containsText, and qualityFlags), controlled vocabulary rules, and an **acceptance-criteria checklist** ("every source image has exactly one record", "captions are 1-2 sentences", "tags use a consistent vocabulary", "the JSON parses"). Save the schema + checklist to artifact `image-index/schema.md` with `write_artifact`; note the path in task notes. - Describe each imagedeveloper
read each image, write structured descriptions
Show working prompt
Read artifact `image-index/schema.md` with `read_artifact`, then list the source image folder with workspace tools. For each image, use the available image-reading or description capability to populate the schema. If the user supplied an authoritative metadata sidecar because image binaries or vision are unavailable, read it with `read_file`, preserve only its facts, and record that limitation. Keep vocabulary consistent and do not skip or invent images. Stage the complete per-image array as valid workspace JSON at `work/image-descriptions.json` with `write_file`.
- Assemble the indexdeveloper
write the index file in the chosen format
Show working prompt
Read workspace `work/image-descriptions.json` with `read_file`, reconcile it against the complete source-folder or sidecar listing, and write the final JSON object to workspace `index.json` with `write_file`. Ensure the `images` array has exactly one record per source filename, every required field is present, and vocabulary is consistent. On a loop-back, fix only the named gaps (missing/extra records, malformed JSON, inconsistent tags). `write_task_note` the index path and an explicit coverage count (records vs source images).
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Read workspace `index.json`, `work/image-descriptions.json`, and the source-folder listing with workspace tools, plus artifact `image-index/schema.md` with `read_artifact`. Check coverage and consistency: does every source image have exactly one record, do all required fields exist, do captions/tags follow the schema and a consistent vocabulary, and does the file parse? Spot-check descriptions against actual images when available. Write PASS/FAIL per criterion. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "assemble" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every criterion passed. Write a DONE summary: index path, format, image count, and a one-line note that coverage is complete and the schema is consistent.
Triggers
Phrases that suggest this craftbook to a crew.
- index images
- describe images
- caption a folder
- image catalog
Source
View this craftbook on GitHub · MIT license