AGENTS.md

Guidance for coding agents working on Gumroad Codex Agent Workspace. Humans can start with README.md; this guide captures the workflow rules, commands, safety gates, and file conventions an agent needs before creating or publishing a Gumroad product.

Project Overview

This repository is a manual Codex harness for creating one Gumroad digital product at a time. The project is Markdown-agent first: role prompts in agents/, reusable instructions in skills/*/SKILL.md, roadmap memory in roadmap/product-roadmap.md, and deterministic Python scripts under scripts/ carry the workflow.

The default product shape is a PDF quickstart plus editable template ZIP, with richer AI execution kits encouraged when the product needs reusable agent cards, LLM skills, checklists, HTML micro-tools, trackers, or credential-safe automation files. Product source lives in products/<slug>/product.json; generated outputs live under products/<slug>/build/.

Hard Boundaries

Do not create background agents, cron jobs, gateway services, databases, shell wrappers, autonomous bulk publishing loops, hidden long-running services, or unattended publishing behavior.

Do not publish unless the owner explicitly asks for publish mode. A request through an external bridge counts only when its natural-language text clearly asks to publish, release, or push a prepared product live.

Do not treat personal-work-agent global memory as Gumroad source of truth. Long-term Gumroad-specific memory belongs in repository Markdown under research/agent-memory/.

Do not bypass access controls, harvest buyer data, copy competitor copy/images/outlines, or claim verified sales, revenue, ranking, testimonials, or outcomes unless a source explicitly exposes that fact.

Source Reading Order

For product work, read these files in order before making product decisions:

agents/orchestrator.md
roadmap/product-roadmap.md
skills/taste-driven-product-judgment/SKILL.md
The role files referenced by agents/orchestrator.md
The skill files referenced by those roles
schemas/product.schema.json
The deterministic scripts under scripts/

The required global judgment skill is skills/taste-driven-product-judgment/SKILL.md. Apply it before adding product content, page copy, images, discounts, publish changes, or marketing assets. Every new product meeting must record the buyer decision moment, one thing kept, one thing cut, and the trust risk avoided.

Setup Commands

The project expects Python 3.12 or newer. Dependencies are declared in pyproject.toml:

bashcd /home/hukhanbang/code/gumroad
UV_LINK_MODE=copy UV_PROJECT_ENVIRONMENT="$HOME/.cache/gumroad-codex-agent-venv" uv run python --version

The project uses local Gumroad CLI authentication for account operations:

bashgumroad auth login

Normal rendering commands should use the same uv environment variables used in README.md so reportlab, pillow, and edge-tts are available without creating project-local virtualenv churn.

Main Workflow

Default mode is dry-run. A full dry run should create or update products/<slug>/meeting.md, create products/<slug>/product.json, render artifacts, run QA, and run a Gumroad dry-run without publishing.

Use this status snapshot before choosing the next product when Gumroad performance should influence planning:

bashpython3 scripts/gumroad_status.py snapshot --output-dir research

The snapshot script is intentionally read-only. Its command builder allows account, product, sales summary, and payout reads, and rejects mutating Gumroad verbs such as create, update, publish, delete, refund, upload, or export.

Render and QA one prepared product:

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

Run a publish-safe local plan:

bashpython3 scripts/gumroad_cli.py dry-run products/<slug>

Publish only after explicit owner approval and passing QA:

bashpython3 scripts/gumroad_cli.py publish products/<slug>

After a successful publish, create the launch-trailer short package from the published product:

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>

Product Files

Every product run creates exactly one directory under products/<slug>/.

Required source files:

products//meeting.md
products//product.json

Generated files are outputs, not planning documents:

products//build/guide.md
products//build/guide.html
products//build/.pdf
products//build/-templates.zip
products//build/description.html
products//build/manifest.json
products//qa_report.json
products//gumroad_plan.json or products//gumroad_result.json

product.json must match schemas/product.schema.json. Required fields include slug, title, subtitle, audience, promise, summary, price, currency, Gumroad taxonomy details, tags, description HTML, PDF sections, templates, refund policy, disclaimer, support text, originality notes, cover prompt, cover alt text, and page design notes.

Meeting Record

meeting.md is the audit trail, not a transcript. New meetings should include:

Owner Input
Mode
Agent Invocation Ledger
Taste Gate
Gumroad Status Snapshot
CEO Decision
Rejected Alternatives
Market Brief
Product Plan
Content Plan
Support Plan
Page And Cover Plan
QA Notes
Gumroad Result
Marketing Shorts Result in publish mode
Open Risks
Roadmap Update

The Agent Invocation Ledger must distinguish markdown-role-applied from real subagent-delegated execution. Do not claim live subagent delegation unless the current run records a subagent id or returned result file.

Quality Gates

Before Gumroad publishing, confirm:

product.json exists and validates against the project schema.
Product render completed and build/manifest.json exists.
Deterministic QA passed.
Manual QA passed.
meeting.md includes the required ledger and Taste Gate.
Cover and preview images are custom, product-specific, sufficiently large, and not placeholder-like.
Local PDF, template ZIP, and cover PNG exist.
The owner explicitly requested publish mode.

scripts/product_artifacts.py qa enforces content quality rules: blocked claims, minimum content volume, premium product targets, Gumroad taxonomy checks, required source notes, disclaimer coverage, JSON template validity, meeting traceability, custom image quality, and premium packaging checks.

Tests

Run the local test suite with unittest discovery:

bashpython3 -m unittest discover -s tests

The current tests cover:

read-only Gumroad status snapshots and buyer-email exclusion
Gumroad CLI preview image handling and dry-run behavior
product artifact content quality, meeting traceability, source notes, JSON templates, image QA, and premium packaging
discount campaign planning helpers
shorts planning, rendering, and QA behavior

When changing scripts/product_artifacts.py, also inspect tests/test_product_artifacts_content_quality.py; it encodes the strongest workflow and QA invariants.

Role And Skill Conventions

Role files under agents/ are portable Markdown agent cards. Each role starts with YAML frontmatter:

yaml---
name: kebab-case-agent-name
description: "One concise sentence describing when this role should be used."
model: inherit
skills:
  - matching-skill-directory-name
---

Use model: inherit in canonical role files unless the owner explicitly asks for a provider-specific model. If a role uses a skill, keep the skill name in frontmatter and include a normal Markdown link near the top of the body.

Skill files live at skills/<name>/SKILL.md and use Agent Skills frontmatter:

yaml---
name: matching-skill-directory-name
description: Use when ...
---

The skill name must match its directory. Put long references under the skill directory and link to them from SKILL.md instead of overloading the frontmatter.

When adding a new role or skill that becomes part of the core run, update agents/orchestrator.md, the ledger expectations, and the root source hierarchy.

Product Strategy Rules

Prefer products for solo operators, freelancers, creators, consultants, small agencies, and small businesses. Each product should focus on one buyer segment, one AI-assisted workflow or project moment, and one purchase promise.

The roadmap favors practical AI execution kits over generic prompt packs or broad AI productivity claims. Strong products help with scoping, briefing, generating, reviewing, documenting, handing off, or iterating on real work.

New premium paid products normally target USD 29, with USD 20 as the minimum floor unless the owner explicitly requests otherwise. Price must be justified by useful buyer-ready assets, not by inflated file counts or decorative filler.

Do not promise revenue, rankings, traffic, hiring outcomes, platform approval, total automation, guaranteed productivity gains, or professional legal, financial, medical, or tax advice.

Security And Privacy

Do not read or store buyer-level sale records unless an explicit future workflow has a lawful, consented, and necessary reason. The existing status snapshot path intentionally avoids buyer emails and buyer-level records.

Never commit or publish private credentials, Gumroad auth material, API keys, .env* files, personal tokens, or private customer data.

When writing product artifacts that mention integrations or automations, keep them manual, inspectable, credential-safe, and portable. Do not hide credentials in generated files or create background execution paths.

Final Response Shape

For product runs, final chat responses should start with a human-readable title, then a one- or two-sentence summary. Include the current top next action in Korean using the repository's established shape:

markdown<short report title>

<summary>

현재 최우선 다음 액션은:

`<single concrete next action, product name, or blocker>`

Then include concise numbered sections for product directory, Gumroad status snapshot path, PDF path, ZIP path, QA status, dry-run or publish result, and blockers. Avoid tables in final chat responses unless the owner asks for them.

Gumroad Codex Agent Workspace Agent Guide