Skip to content

AGENTS.md

Latest commit

 

History

History
132 lines (87 loc) · 5.73 KB

AGENTS.md

File metadata and controls

132 lines (87 loc) · 5.73 KB

Screenshot Factory — Agent Instructions

This file provides agent instructions for Codex and other AI tools that read AGENTS.md.

Screenshot Factory Setup

When the user asks to set up App Store screenshots, integrate Screenshot Factory, or mentions /setup-screenshots, follow this workflow exactly.

Phase 0 — Bootstrap (silent, automatic — no user input)

Before anything else, ensure the CLI is available:

  1. Run which screenshot-factory. If found, proceed to Phase 1.
  2. If not found, check ./fastlane/ScreenshotFactory/.build/release/screenshot-factory. If found, use it and proceed to Phase 1.
  3. If neither exists:
    • Run: git clone https://github.com/iMark21/ScreenshotFactory ./fastlane/ScreenshotFactory
    • Run: cd ./fastlane/ScreenshotFactory && swift build -c release
  4. Inform the user with a single line: Screenshot Factory ready at ./fastlane/ScreenshotFactory and immediately proceed to Phase 1.

Phase 1 — Questionnaire (4 mandatory stops, read-only)

CRITICAL: Do NOT create, modify, or write ANY files during Phase 1. Wait for the user to reply at each stop before continuing.

Stop 1 of 4 — Prerequisites Check

Run silently, then present results:

  • Is screenshot-factory CLI available? (from Phase 0)
  • Does the project have a UITests target? (*UITests directory or Xcode target)
  • Does fastlane/ exist?
  • What is the .xcodeproj / .xcworkspace and scheme name?

Show a checklist with ✅/❌ for each item. If anything is missing, explain how to fix it.

Ask: "Everything look correct? Should I fix anything before continuing?" Then wait.

Stop 2 of 4 — Project Analysis & Screens

Analyze the project (read files, do not write):

  • Supported locales (from Localizable.xcstrings, .strings, or Info.plist)
  • Brand colors (from Assets.xcassets)
  • 5 key screens for App Store screenshots
  • iPad support (from Info.plist or target settings)

Present the analysis and proposed 5 screens.

Ask: "Are these the right screens? Want to change, add, or remove any? Are the detected locales correct?" Then wait.

Stop 3 of 4 — Design Template

Present the 6 templates and ask the user to choose:

# Template Best for
1 dark-teal-accent Games, social, entertainment
2 space-navy Meditation, lifestyle, health
3 obsidian-minimal Premium, e-commerce, productivity
4 dark-atmospheric Atmospheric, immersive apps
5 light-clean Utilities, tools, professional
6 vibrant-gradient Fitness, social, creative

Ask: "Which template fits your app? Reply with a number (1–6)." Then wait.

Stop 4 of 4 — Confirmation Checklist

Show a summary of all files that will be created (SnapshotHelper.swift, capture.sh, pipeline.sh, Snapfile, screenshots.json, --screenshot-mode entry point, UITest file).

Ask: "Ready to proceed? (yes/no)" Then wait.

Phase 2 — Execution (only after all 4 stops confirmed)

  1. Copy infrastructure from ./fastlane/ScreenshotFactory/Capture/:

    • SnapshotHelper.swift → {UITests target}/
    • capture.sh → fastlane/ (chmod +x)
    • pipeline.sh → fastlane/ (chmod +x)

  2. Create fastlane/Snapfile with project name, scheme, devices (iPhone 17 Pro Max, optionally iPad), and detected languages.

  3. Create fastlane/screenshots.json based on ./fastlane/ScreenshotFactory/Templates/{chosen-template}.json. Adjust brand colors. Generate localized benefit-focused text for each screen and each locale in the locale's native language.

    • keyword: 3–5 words, benefit-focused, use {word} syntax to highlight the hero word
    • subtitle: 1 short sentence
    • es-ES: use Spain Spanish tuteo, never Latin American voseo

  4. Add --screenshot-mode handling to the app's entry point. Create ScreenshotData.swift with realistic mock data.

  5. Create UITest {Scheme}UITests.swift with class {Scheme}UITests, method testGenerateAppStoreScreenshots, using setupSnapshot(app) and snapshot("01-{Name}") calls. Use accessibilityIdentifier for navigation.

  6. Verify: create fastlane/screenshots/ and fastlane/screenshots_framed/ directories.

Rules

  • Write BENEFITS, not features ("Perfect Messages" not "AI Generator")
  • Every locale's text in that locale's native language
  • Raw and framed screenshots in separate directories
  • Each device class needs its own captures (never reuse iPhone for iPad)

Screenshot Factory Uninstall

When the user says "uninstall", "remove", or "desinstalar" Screenshot Factory, follow this workflow.

Step 1 — Scan

Silently check which files/directories exist in the project:

  • fastlane/Snapfile, fastlane/screenshots.json, fastlane/capture.sh, fastlane/pipeline.sh
  • fastlane/screenshots/, fastlane/screenshots_framed/
  • fastlane/ScreenshotFactory/ (cloned repo)
  • {UITests target}/SnapshotHelper.swift
  • {UITests target}/{Scheme}UITests.swift
  • --screenshot-mode block in the app entry point
  • ScreenshotData.swift

Step 2 — Confirm

Show what will be removed and ask two extra questions:

  • "Also remove ./fastlane/ScreenshotFactory/ (the cloned tool)? (yes/no)"
  • "Also remove {Scheme}UITests.swift? (only if it contains ONLY screenshot tests)"

Ask: "Confirm uninstall? (yes/no)" Do NOT delete anything until confirmed.

Step 3 — Execute

  1. Delete confirmed files and directories.
  2. {Scheme}UITests.swift: if it only has testGenerateAppStoreScreenshots → delete file. If it has other tests → remove only that method and tapTab helper.
  3. App entry point: remove the --screenshot-mode block. Delete ScreenshotData.swift if it exists.
  4. fastlane/ScreenshotFactory/: delete only if user said yes.

Step 4 — Report

Show a summary of what was removed and what was skipped.