Skip to content

README.md

Latest commit

 

History

History
333 lines (236 loc) · 11.1 KB

README.md

File metadata and controls

333 lines (236 loc) · 11.1 KB

PodStack

One repo, one install, entire podcast content workflow — works with Claude Code, OpenAI Codex, Cursor, opencode, or any AI tool that reads markdown.

PodStack turns your AI coding tool into a full podcast content team using structured skill files. It gives you an Episode Architect, Content Analyst, Title Writer, Copywriter, Art Director, Brand Guardian, Producer, Launch Manager, and Performance Analyst — all driven from your terminal or editor.

Built for podcasters who use podcli but works standalone with any project.

Inspired by gstack by Garry Tan.

What You Get

Command Role What It Does
/plan-episode Episode Architect Designs questions, story arc, moment map BEFORE recording
/process-transcript Content Analyst Ingests transcript → extracts best moments → scores → categorizes
/generate-titles Title Writer Generates 8 title options with full verification checklist
/generate-descriptions Copywriter Creates descriptions + hashtags + SEO keywords
/plan-thumbnails Art Director Plans thumbnail text + layout briefs for your designer
/review-content Brand Guardian Fix-First review: auto-fixes + parallel specialist dispatch
/produce-shorts Producer Full pipeline: transcript → publish-ready package
/publish-checklist Launch Manager Pre/post-publish optimization checklist
/retro-episode Analyst Episode performance review + appends patterns to knowledge/13-learnings.md

Host Compatibility

PodStack ships one source-of-truth in commands/ and installs to the right location for whichever tool you use:

Host Install location Primary instruction doc
Claude Code (default) .claude/commands/*.md CLAUDE.md
OpenAI Codex .codex/prompts/*.md AGENTS.md
Cursor .cursor/rules/*.mdc AGENTS.md
opencode .opencode/commands/*.md AGENTS.md
Generic (anything else) commands/*.md AGENTS.md

setup.sh auto-detects your tool based on existing .claude/, .codex/, .cursor/, or .opencode/ folders. Override with --host.

Install

Option 1: With podcli (recommended for podcasters)

If you already use podcli:

# From your podcli project directory
npx podstack init

This detects your AI tool and installs commands + knowledge base templates in .podcli/knowledge/.

Option 2: Standalone — auto-detect host

# Clone into your project
git clone https://github.com/nmbrthirteen/podstack.git .podstack

# Auto-detect Claude Code / Codex / Cursor / opencode
.podstack/setup.sh

Option 3: Standalone — explicit host

# For Claude Code
.podstack/setup.sh --host claude-code

# For OpenAI Codex
.podstack/setup.sh --host codex

# For Cursor (converts .md → .mdc rules)
.podstack/setup.sh --host cursor

# For opencode
.podstack/setup.sh --host opencode

# For any other tool (copies to project-root commands/ + AGENTS.md)
.podstack/setup.sh --host generic

Option 4: Global install

# Install globally so it's available in any project
git clone https://github.com/nmbrthirteen/podstack.git ~/.podstack

Then from any project: ~/.podstack/setup.sh

Usage by Host

Claude Code

/plan-episode
/produce-shorts
/retro-episode

Commands appear in /help. Claude reads CLAUDE.md automatically.

OpenAI Codex

Codex reads AGENTS.md at project root on startup. Invoke skills by reference:

Run the produce-shorts playbook on transcripts/ep42.txt
Use the generate-titles skill for this clip: [paste]

Codex loads the referenced file from .codex/prompts/ and follows it.

Cursor

Rules live in .cursor/rules/*.mdc. Invoke in chat:

Use the produce-shorts rule on this transcript
Apply the review-content rule to the content package at episodes/ep42.md

Cursor matches rules by description.

opencode

Commands work like Claude Code slash commands:

/plan-episode
/produce-shorts

Generic tool

Point your AI at AGENTS.md and reference skills by path:

Follow the instructions in commands/produce-shorts.md using this transcript: [paste]

Quick Start

1. Set up your brand

Edit the knowledge base files in knowledge/ (or .podcli/knowledge/ if using podcli):

knowledge/
├── 00-master-instructions.md    ← Your show's AI operating system
├── 01-brand-identity.md         ← Who you are, positioning, hosts
├── 02-voice-and-tone.md         ← How you sound, banned words
├── 03-episodes-database.md      ← Track episodes and existing shorts
├── 04-shorts-creation-guide.md  ← Moment selection criteria
├── 05-title-formulas.md         ← Your title patterns and rules
├── 06-descriptions-template.md  ← Description templates + hashtags
├── 07-thumbnail-guide.md        ← Visual specs for your brand
├── 08-topics-themes.md          ← Your content categories
├── 09-content-workflow.md       ← End-to-end workflow
├── 10-internal-processing.md    ← Internal rules for your AI
├── 11-inspiration-channels.md   ← Reference channels you admire
├── 12-quick-reference.md        ← Copy-paste resources
└── 13-learnings.md              ← Cross-episode learnings (auto-updated by /retro-episode)

Each file ships as a starter template with examples. Fill them in with your show's specifics.

2. Process your first episode

/produce-shorts

Paste your transcript or point to a file. PodStack runs the full pipeline and delivers a publish-ready content package.

3. Or use individual commands

/process-transcript     ← Just extract moments from a transcript
/generate-titles        ← Just get title options for a specific clip
/review-content         ← Just review existing content for quality

The Pipeline (Sprint Workflow)

Plan → Process → Write → Review → Publish → Retro

/plan-episode  →  [record]  →  /process-transcript  →  /generate-titles  →  /generate-descriptions
                                                                                    ↓
             /retro-episode  ←  [published]  ←  /publish-checklist  ←  /review-content  ←  /plan-thumbnails

Or run everything at once: /produce-shorts

After publishing: /retro-episode — also appends cross-episode learnings so future runs get smarter.

How It Works

PodStack skills are plain markdown files with YAML frontmatter. Each one shifts your AI into a specialized role. Every skill includes:

  • Frontmatter — description, allowed-tools, argument-hint, triggers (natural language phrases that auto-route to the skill)
  • A clear role — what the agent is acting as (analyst, writer, reviewer)
  • An execution protocol — step-by-step instructions
  • Quality gates — checks that must pass before output
  • Output format — structured, consistent deliverables
  • Completion Protocol — every skill returns DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_INPUT with evidence
  • Three-Strike Rule — orchestrators abort after 3 consecutive phase failures instead of looping
  • Reference file pointers — links to your knowledge base for detailed specs

The knowledge base files are your show's "brand brain" — they contain your voice, style, title formulas, banned words, and everything needed to produce content that sounds like you, not generic AI.

/review-content also uses Fix-First with parallel specialist dispatch — it auto-applies mechanical fixes (banned words, hashtag dedup, casing) and batches human-decision items into one question.

Customization

Add your own skills

Create any .md file in commands/ (or your host's command folder) with the frontmatter format:

---
description: What the skill does
allowed-tools: Read, Write
argument-hint: [what the user types]
triggers:
  - natural language phrase 1
  - natural language phrase 2
---

# /my-custom-skill — My Role

> Instructions for the agent...

## Execution Protocol
...

## Completion
Return DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_INPUT per CLAUDE.md or AGENTS.md.

Re-run ./setup.sh to install it for your host.

Modify existing skills

All skills are plain markdown. Edit them to match your workflow. Common customizations:

  • Change the number of title options (default: 8)
  • Add your own quality gates
  • Add new specialists to /review-content
  • Modify output formats
  • Add new content types beyond the default five

podcli integration

When installed with podcli, skills automatically have access to:

  • transcribe_podcast — Whisper transcription with speaker detection
  • suggest_clips — AI-powered moment extraction
  • create_clip — Render clips with captions and smart cropping
  • knowledge_base — Read/write your brand files
  • clip_history — Track what's been generated

Project Structure

podstack/
├── README.md                    ← You are here
├── CLAUDE.md                    ← Claude Code-specific primary doc
├── AGENTS.md                    ← Host-agnostic primary doc (Codex, Cursor, opencode, generic)
├── ETHOS.md                     ← Content philosophy (the why behind every rule)
├── CHANGELOG.md                 ← Release history
├── VERSION                      ← Current version
├── LICENSE
├── setup.sh                     ← Host-detecting installer (--host flag)
├── commands/                    ← Skill files (with YAML frontmatter) — source of truth
│   ├── plan-episode.md
│   ├── process-transcript.md
│   ├── generate-titles.md
│   ├── generate-descriptions.md
│   ├── plan-thumbnails.md
│   ├── review-content.md
│   ├── produce-shorts.md
│   ├── publish-checklist.md
│   └── retro-episode.md
└── templates/                   ← Starter knowledge base files
    ├── 00-master-instructions.md
    ├── 01-brand-identity.md
    ├── 02-voice-and-tone.md
    ├── 03-episodes-database.md
    ├── 04-shorts-creation-guide.md
    ├── 05-title-formulas.md
    ├── 06-descriptions-template.md
    ├── 07-thumbnail-guide.md
    ├── 08-topics-themes.md
    ├── 09-content-workflow.md
    ├── 10-internal-processing.md
    ├── 11-inspiration-channels.md
    ├── 12-quick-reference.md
    └── 13-learnings.md

Requirements

License

MIT