Skip to content

AGENTS.md

Latest commit

 

History

History
98 lines (70 loc) · 4.24 KB

AGENTS.md

File metadata and controls

98 lines (70 loc) · 4.24 KB

podguy project instructions

This repository is primarily operated through pi for podcast post-production work.

Default to the podguy-post-production workflow unless the user explicitly asks for something else. Use podguy-clip-cutter when the user asks to export or cut social clips.

Primary tasks

  • scan episode videos for likely interstitials and non-host inserts when video is available
  • generate transcripts for draft, preview, or final episode exports
  • derive YouTube/podcast chapters in timestamp-title format
  • give editorial feedback such as cuts, highlights, weak sections, and insert opportunities
  • cut selected highlight moments into review exports for TikTok, Reels, YouTube Shorts, trailers, or social posts
  • draft publishing assets such as show notes, quote sheets, and proper noun review

Podcast profile

  • Prefer show-specific settings from podguy.toml when present.
  • Use podguy.example.toml as the template for new shows.
  • Do not assume a specific show, hosts, audience, tone, or episode naming convention unless the profile or user provides it.

Working guidance

  • prefer writing generated outputs under dist/analysis/
  • reuse existing analysis outputs when they already match the requested episode/version
  • treat scanner results as heuristic review aids, not exact edit points
  • support audio-only files, video drafts, preview exports, and final renders
  • skip the visual scanner for audio-only inputs
  • use transcript evidence and timecodes whenever possible when giving editorial feedback
  • treat generated clip media as review exports, not final mastered social edits
  • use scripts/download_sample_media.sh when a real open-license video-podcast sample is helpful; keep downloaded samples under gitignored dist/

Interaction guidance

  • assume the user will speak in natural language, not remember slash commands
  • treat prompt templates as optional shortcuts, not required UX knowledge
  • if the user asks for something ambiguous like "analyze this" or "review this episode", ask one short clarifying question before deciding how much to generate
  • prefer offering simple natural-language choices rather than command names

Default clarification for ambiguous episode requests:

  • quick pass = optional video scan + transcript + prepared transcript artifacts + short summary
  • full review = quick pass + chapters + clips + cuts + show notes + quotes + proper noun review

If the user request already clearly asks for one specific deliverable, do that directly instead of asking.

For synthetic or test fixture inputs, default to a leaner evaluation mindset:

  • prefer a quick pass unless the user explicitly asks for a full editorial bundle
  • treat fixtures as test media, not normal production exports, unless the user says otherwise

Important entry points

  • Launcher: podguy
  • Startup extension: src/podguy-startup.ts
  • Post-production skill: src/podguy-post-production/SKILL.md
  • Clip-cutter skill: src/podguy-clip-cutter/SKILL.md
  • Transcript CLI: scripts/transcribe_video.py
  • Transcript prep CLI: scripts/prepare_transcript_analysis.py
  • Scanner CLI: scripts/scan_podcast.swift
  • Clip cutter CLI: scripts/cut_clips.py

Validation commands

Run the full local validation surface before opening PRs:

npm run format:check
npm run lint
npm run typecheck
npm test

For direct shell smoke tests, run:

bash scripts/test.sh

Changelog guidance

Maintain top-level CHANGELOG.md as the source of truth for user-visible changes.

  • Keep upcoming work under ## [Unreleased] with ### Added, ### Changed, and ### Fixed subsections.
  • Append to existing subsections instead of creating duplicates.
  • When cutting a release, move relevant unreleased entries into a new immutable version section and start a fresh ## [Unreleased] section.
  • Use the released changelog section as the starting point for the GitHub release body.
  • Prefer gh release create/edit --notes-file for multi-line release notes.
  • Do not trust autogenerated GitHub release notes blindly; verify and edit them.
  • Prefer concise user-visible entries over internal refactor details unless behavior changed.

Commit conventions

Commit titles should follow Conventional Commits where practical:

<type>[scope]: <description>