AlexandrAI AGENTS.md
agents-md

Gumroad Shorts Scriptwriter Agent Guide

Project-specific AGENTS.md guidance for the Gumroad shorts scriptwriter role, post-publish trailer inputs, story arc, captions, storyboard, and non-hard-sell constraints.

AGENTS.md

Guidance for coding agents working on the Gumroad shorts scriptwriter role.

Project Overview

The shorts scriptwriter runs only after a Gumroad product is published. It writes a restrained vertical launch trailer script, captions, and storyboard from the real product page, cover, preview images, PDF and template promise, and published product URL.

Source Files

  • agents/shorts-scriptwriter.md defines the role.
  • skills/shorts-marketing-workflow/SKILL.md defines the trailer standard and deterministic commands.
  • products//gumroad_result.json proves the product is live.
  • products//product.json supplies title, promise, file inventory, and support boundaries.
  • products//build/manifest.json supplies artifact paths.
  • products//assets/cover.png and assets/page-images/ supply visual proof when present.
  • products//marketing/shorts/launch-trailer/ is the output directory.

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>

If TTS is unavailable, render a captioned silent draft and do not claim voiceover exists.

Change Rules For Agents

  • Do not create launch-ready shorts before publish evidence exists.
  • Keep the script 45 to 60 seconds, with default final render at 60 seconds.
  • Start with a buyer-recognizable question, tension, or pattern interrupt.
  • Use at least 8 scenes or visual cuts.
  • Use real product assets as proof: cover, preview pages, template names, file count, PDF, or ZIP.
  • Make the story arc tension, mess, transformation, proof, payoff, soft CTA.
  • Avoid buy-now language, fake urgency, discounts unless explicitly requested, fake reviews, fake results, and guaranteed outcomes.
  • Do not promise revenue, rankings, traffic, conversion, or business results.
  • Do not make a static slideshow with bottom-only captions.

Output Files

Expected outputs include shorts_manifest.json, trailer_script.md, voiceover.txt when available, storyboard.csv, captions.srt, hyperframe_brief.md, frames, scene clips, final MP4, and qa_report.json.

Verification

bashUV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python scripts/shorts_artifacts.py qa products/<slug>

Confirm the manifest product URL matches the published result and that the video package is not treated as launch-ready until QA passes.

Security Notes

Do not include private product ids, credentials, buyer data, private endpoints, or local absolute paths in public scripts, captions, storyboards, or metadata. The short should point viewers to the public Gumroad page only through the product output.

PR Checklist

  • gumroad_result.json proves publish status.
  • Cold open is specific.
  • Script uses real product artifacts.
  • At least 8 scenes are planned.
  • Claims stay operational and non-guaranteed.
  • Shorts QA passes before launch-ready status.