AlexandrAI AGENTS.md
agents-md

Gumroad Shorts Artifacts Script Agent Guide

Project-specific AGENTS.md guidance for scripts/shorts_artifacts.py, post-publish trailer planning, storyboard generation, captions, local render, TTS fallback, and shorts QA.

AGENTS.md

Guidance for coding agents working on scripts/shorts_artifacts.py.

Project Overview

scripts/shorts_artifacts.py plans, renders, and QA-checks one vertical product trailer for a published Gumroad product. It requires published-product proof unless explicitly allowed for tests or drafts. It writes script, voiceover text, captions, storyboard, render brief, social metadata, upload checklist, frames, MP4, render result, and QA report.

Source Files

  • scripts/shorts_artifacts.py owns plan_short(), render_short(), qa_short(), storyboard generation, visual asset collection, TTS, local video render, and QA.
  • agents/video-marketing-strategist.md, shorts-scriptwriter.md, hyperframe-video-producer.md, tts-voiceover-producer.md, shorts-qa-manager.md, and social-shorts-publisher.md use its outputs.
  • products//gumroad_result.json proves publish status.
  • products//product.json supplies product facts.
  • tests/test_shorts_artifacts.py covers publish requirement, hard-sell language avoidance, stale-copy detection, silent render, and QA.

Setup Commands

bashUV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py plan products/<slug>
UV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py render products/<slug> --tts edge
UV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py qa products/<slug>
python -m unittest tests/test_shorts_artifacts.py

Use --tts none when creating an intentional captioned silent draft.

Change Rules For Agents

  • Require published Gumroad proof before launch-ready shorts.
  • Keep default duration at 60 seconds.
  • Keep vertical mobile output dimensions at 1080 by 1920.
  • Keep at least 8 scenes or cuts.
  • Keep hard-sell patterns blocked: buy-now language, fake scarcity, guarantees, secret hacks, and make-money claims.
  • Keep stale product copy checks so scripts do not mention unsupported AI, LLM, skill, or scorecard positioning.
  • Collect real visual assets from cover and page images.
  • Record layout safety so text and product imagery do not overlap.
  • Preserve silent fallback reporting when TTS is unavailable.

Verification

Run the unit test and shorts QA. Watch the rendered video when present. Confirm captions, storyboard, product URL, visual assets, duration, dimensions, and non-hard-sell language.

Security Notes

Do not store platform credentials, private account ids, buyer data, local absolute paths in public metadata, fake analytics, or unapproved platform tokens in shorts outputs.

PR Checklist

  • Plan requires published product unless explicitly bypassed for test or draft.
  • Storyboard has at least 8 cuts.
  • Captions and social metadata are generated.
  • Render result records layout safety.
  • QA passes before launch-ready status.