claude-configs/skills/paper-dynasty/SKILL.md

name	description
paper-dynasty	Paper Dynasty baseball card game management. USE WHEN user mentions Paper Dynasty, gauntlet teams, player cards, scouting reports, pack distribution, rewards, or card game database operations.

Paper Dynasty - Baseball Card Game Management

SCOPE: Only use in paper-dynasty, paper-dynasty-database repos. Do not activate in unrelated projects.

---

When to Activate This Skill

Database Operations:

• "Sync prod to dev" / "Copy production database"
• "Pull production data to dev"

Structured Operations:

• "Clean up gauntlet team [name]"
• "Generate weekly cards" / "run card workflow"
• "Update scouting" / "regenerate scouting reports"
• "Distribute [N] packs to all teams"
• "Wipe team [abbrev] cards"

Discord Bot Troubleshooting:

• "Check pd-discord logs" / "restart bot"
• "Is the bot running?" / "bot status"

Ad-Hoc Queries:

• "How many cards does team SKB have?"
• "Show me all MVP rarity players"
• "List all teams in season 5"
• "Find active gauntlet runs"

Ecosystem & Cross-Project:

• "PD status" / "ecosystem status" / "what needs work"
• "Show PD ecosystem status" / "What's the status across all projects?"

Growth & Engagement:

• "growth roadmap" / "engagement" / "user retention"

For deployment, use the deploy skill instead.

---

What is Paper Dynasty?

A baseball card TCG with digital player cards, team collection, game simulation, and gauntlet tournaments.

Key Components:

• API: pd.manticorum.com (prod) / pddev.manticorum.com (dev)
• Discord Bot: On sba-bots server
• Card Generation: /mnt/NV2/Development/paper-dynasty/card-creation/

---

Critical Rules

CLI-First for ALL Operations

✅ ALWAYS use CLI tools first — they handle auth, formatting, and error handling ❌ NEVER write raw Python API calls when a CLI command exists ❌ NEVER access local SQLite directly

paperdomo CLI (queries, packs, gauntlet, teams):

python ~/.claude/skills/paper-dynasty/cli.py [command]

pd-cards CLI (card generation, scouting, uploads):

cd /mnt/NV2/Development/paper-dynasty/card-creation
pd-cards [command]

Only fall back to the Python API (api_client.py) for complex multi-step operations that the CLI doesn't cover (e.g., batch cleanup loops, custom card creation).

For CLI reference: reference/cli-overview.md (links to per-command files)

---

Workflows

Workflow	Trigger	Quick Command
Database Sync	"Sync prod to dev"	~/.claude/skills/paper-dynasty/scripts/sync_prod_to_dev.sh
Gauntlet Cleanup	"Clean up gauntlet team X"	$PD gauntlet cleanup Gauntlet-X -e N -y
Pack Distribution	"Give N packs to everyone"	$PD pack distribute --num N
Scouting Update	"Update scouting"	pd-cards scouting all -c 27
Card Generation (Retrosheet)	"Generate cards for 2005"	Use retrosheet-card-update agent
Card Generation (Live Series)	"Update live series cards"	Use live-series-card-update agent
Custom Cards	"Create custom player"	pd-cards custom preview name
S3 Upload	"Upload cards to S3"	pd-cards upload s3 -c "2005 Live"
Bot Troubleshooting	"Check bot logs"	ssh sba-bots "docker logs paper-dynasty_discord-app_1 --tail 100"

Detailed workflow docs: workflows/ directory

Gauntlet Cleanup Safety

Safe to clean: Gauntlet teams (temporary), completed runs, eliminated teams Never clean: Regular season teams, teams with active gameplay, before tournament ends

Data	Action	Reversible?
Cards	Unassigned (team = NULL)	Yes (reassign)
Packs	Deleted	No
Run Record	Ended (timestamp set)	Kept in DB
Team/Results/Stats	Preserved	Kept in DB

Batch cleanup (all active runs in an event):

runs = api.list_gauntlet_runs(event_id=8, active_only=True)
for run in runs:
    team_id = run['team']['id']
    api.wipe_team_cards(team_id)
    for pack in api.list_packs(team_id=team_id):
        api.delete_pack(pack['id'])
    api.end_gauntlet_run(run['id'])

Database Sync Notes

Restore a dev backup:

BACKUP_FILE=~/.paper-dynasty/db-backups/paperdynasty_dev_YYYYMMDD_HHMMSS.sql
ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < "$BACKUP_FILE"

Manual fallback (if script fails):

ssh akamai "docker exec sba_postgres pg_dump -U pd_admin -d pd_master --clean --if-exists" > /tmp/pd_prod_dump.sql
ssh pd-database "docker exec -i sba_postgres psql -U sba_admin -d paperdynasty_dev" < /tmp/pd_prod_dump.sql

Large databases: Pipe through gzip/gunzip for compressed transfer.

---

Discord Bot

Server: sba-bots (10.10.0.88) | Container: paper-dynasty_discord-app_1 | Compose Dir: /home/cal/container-data/paper-dynasty/

Related services: PostgreSQL (paper-dynasty_db_1), Adminer (paper-dynasty_adminer_1, port 8080 — user: postgres, pass: example, server: db)

# Check status
ssh sba-bots "docker ps --filter name=paper-dynasty"

# View logs
ssh sba-bots "docker logs paper-dynasty_discord-app_1 --tail 100"

# Follow logs
ssh sba-bots "docker logs paper-dynasty_discord-app_1 -f --tail 50"

# Restart bot
ssh sba-bots "cd /home/cal/container-data/paper-dynasty && docker compose restart discord-app"

# Database CLI
ssh sba-bots "docker exec -it paper-dynasty_db_1 psql -U postgres"

Key env vars (in docker-compose.yml): BOT_TOKEN, GUILD_ID, API_TOKEN, DATABASE (Prod/Dev), LOG_LEVEL, DB_URL (usually db), SCOREBOARD_CHANNEL

---

Common Patterns

PD="python ~/.claude/skills/paper-dynasty/cli.py"

# Teams
$PD team get SKB                          # Single team details
$PD team list --season 10                 # All teams in a season
$PD team cards SKB                        # Team's card collection

# Players
$PD player get 12785                      # Single player details
$PD player list --rarity MVP --cardset 27 # Filtered player list

# Packs
$PD status                                # Packs opened today
$PD pack list --team SKB --unopened       # Team's unopened packs
$PD pack distribute --num 10              # Give 10 packs to all teams
$PD pack distribute --num 5 --exclude CAR # Exclude a team

# Gauntlet
$PD gauntlet list --active                # Active gauntlet runs
$PD gauntlet teams --active               # Active gauntlet teams
$PD gauntlet cleanup Gauntlet-SKB -e 9 -y # Wipe a gauntlet team

Add --json to any command for machine-readable output. Add --env dev for dev database.

---

Quick Reference

Environment Setup

export API_TOKEN='your-token'
export DATABASE='prod'  # or 'dev'

Key IDs

• Current Live Cardset: 27 (2005 Live)
• Default Pack Type: 1 (Standard)
• Rarities: Replacement < Reserve < Starter < All-Star < MVP < Hall of Fame

For full schema: reference/database-schema.md

pd-cards Commands

cd /mnt/NV2/Development/paper-dynasty/card-creation

pd-cards custom list/preview/submit              # Custom cards
pd-cards scouting all -c 27                      # Scouting reports
pd-cards retrosheet process 2005 -c 27 -d Live   # Card generation
pd-cards upload s3 -c "2005 Live"                # S3 upload

paperdomo Commands

PD="python ~/.claude/skills/paper-dynasty/cli.py"
$PD health                        # API health check
$PD status                        # Packs opened today
$PD team list/get/cards            # Team operations
$PD player get/list                # Player operations
$PD pack list/today/distribute     # Pack operations
$PD gauntlet list/teams/cleanup    # Gauntlet operations

---

File Structure

~/.claude/skills/paper-dynasty/
├── SKILL.md              # This file (routing & quick reference)
├── api_client.py         # Python API client
├── cli.py                # paperdomo CLI
├── reference/
│   ├── database-schema.md    # Models, cardsets, pack types, rarities
│   ├── api-reference.md      # Endpoints, authentication, client examples
│   ├── cli-overview.md       # CLI routing table — load this first
│   └── cli/
│       ├── team.md           # team list/get/cards
│       ├── pack.md           # pack list/today/distribute + pack type IDs
│       ├── player.md         # player get/list
│       ├── gauntlet.md       # gauntlet list/teams/cleanup
│       └── pd-cards.md       # custom/scouting/retrosheet/upload/live-series
├── workflows/
│   ├── card-generation.md       # Retrosheet reference (pipeline now in retrosheet-card-update agent)
│   ├── live-series-update.md    # Live series reference (pipeline now in live-series-card-update agent)
│   ├── card_utilities.py        # Card refresh pipeline (fetch → S3 → update)
│   ├── custom-card-creation.md  # Archetypes, manual creation, rating rules
│   └── TROUBLESHOOTING.md       # Card rendering issues
└── scripts/
    ├── distribute_packs.py
    ├── gauntlet_cleanup.py
    └── validate_database.py

Related Codebases:

• Database/API: /mnt/NV2/Development/paper-dynasty/database/
• Discord Bot: /mnt/NV2/Development/paper-dynasty/discord-app/
• Card Creation: /mnt/NV2/Development/paper-dynasty/card-creation/

---

When to Load Additional Context

Need	Load
Database model details	reference/database-schema.md
API endpoints & client usage	reference/api-reference.md
CLI command reference	reference/cli-overview.md → load cli/team.md, cli/pack.md, cli/player.md, cli/gauntlet.md, or cli/pd-cards.md
Retrosheet card workflow / PotM	Use retrosheet-card-update agent (ref: workflows/card-generation.md)
Live series workflow / PotM	Use live-series-card-update agent (ref: workflows/live-series-update.md)
Card rendering issues	workflows/TROUBLESHOOTING.md

---

---

Ecosystem Dashboard

Provides a cross-project view of all Paper Dynasty Gitea repos in a single terminal dashboard.

Script: ~/.claude/skills/paper-dynasty/scripts/ecosystem_status.sh

Trigger phrases:

• "Show PD ecosystem status"
• "What's the status across all projects?"
• "PD status" / "ecosystem status" / "what needs work"

Usage:

# Requires GITEA_TOKEN in env (or auto-reads from gitea-mcp config)
~/.claude/skills/paper-dynasty/scripts/ecosystem_status.sh

What it shows:

• Open issue count per repo
• Open PR count per repo
• Latest commit SHA + date per repo
• Recent commits (last 3) per repo with author and message
• Open issue titles grouped by repo (with labels)
• Open PR titles grouped by repo (with branch info)
• Cross-repo totals

Repos covered: paper-dynasty-database, paper-dynasty-discord, paper-dynasty-card-creation, paper-dynasty-website

Auth: Uses GITEA_TOKEN env var. If unset, attempts to read from ~/.config/claude-code/mcp-servers/gitea-mcp.json.

---

Initiative Tracker (pd-plan)

Local SQLite database tracking cross-project initiatives, priorities, and status.

CLI: python ~/.claude/skills/paper-dynasty/plan/cli.py [command] Database: ~/.claude/skills/paper-dynasty/plan/initiatives.db

Trigger phrases:

• "what should I work on" / "what's the priority"
• "initiative status" / "pd-plan" / "show priorities"
• "update initiative" / "mark done"

Quick reference:

PDP="python ~/.claude/skills/paper-dynasty/plan/cli.py"

$PDP summary                         # Dashboard — run at session start
$PDP list                            # All active initiatives
$PDP list --phase 1                  # Phase 1 only
$PDP list --repo discord             # Filter by repo
$PDP next                            # Highest priority non-blocked item
$PDP next --repo discord             # Next for a specific repo
$PDP show 1                          # Full details + activity log
$PDP add "Title" --phase 1 --priority 20 --impact retention --size M --repos discord
$PDP update 3 --status in_progress --actor pd-discord
$PDP update 3 --note "Merged 8 PRs" --actor pd-ops
$PDP update 3 --link "discord#104"   # Append linked issue
$PDP done 3 --actor pd-ops           # Mark complete
$PDP list --json                     # Machine-readable output

Session startup: Always run pd-plan summary at the start of a Paper Dynasty session to understand current priorities.

---

Growth Roadmap

High-level roadmap for Paper Dynasty player growth, engagement, and retention strategies.

File: /mnt/NV2/Development/paper-dynasty/ROADMAP.md

Trigger phrases:

• "growth roadmap" / "engagement" / "user retention"
• "what's planned" / "next features"

Load the roadmap file for context before discussing growth priorities, feature planning, or retention strategies. Use pd-plan for current status of specific initiatives.

---

Specialized Agents

Dispatch work to these agents for their respective domains. Do not do their work inline — launch them explicitly.

Agent	Model	Domain	Dispatch When
pd-database	Opus	Database/API	Schema changes, endpoints, migrations, data model
pd-discord	Opus	Discord bot	Commands, gameplay engine, bot UX
pd-cards	Opus	Card pipeline	Card generation, ratings, scouting, rendering
pd-growth	Opus	Product growth	Engagement, retention, roadmap prioritization
pd-ops	Sonnet	Release ops	Merging PRs, deploys, branch cleanup, process

PO agents (Opus) decide what to build. pd-ops ensures it ships correctly. Implementation is delegated to engineer, issue-worker, or swarm-coder.

How to dispatch: Mention the agent name explicitly, e.g. "use the pd-cards agent to regenerate scouting" or "dispatch to pd-database for this migration".

---

Last Updated: 2026-03-22 Version: 2.8 (Added pd-plan initiative tracker, pd-ops agent, updated agent table with models)