---
title: "Paper Dynasty Ecosystem Organization & Growth Engine Foundation"
description: "Major organizational session — built cross-project infrastructure, cleared PR backlog (21 merged, 15 closed), established PO agent hierarchy, initiative tracker, and Refractor naming."
type: context
domain: paper-dynasty
tags: [paper-dynasty, organization, infrastructure, agents, roadmap]
---

# Paper Dynasty Ecosystem Organization & Growth Engine Foundation

**Date:** 2026-03-22
**Scope:** Cross-project (all Paper Dynasty repos)

## What Was Done

Transformed Paper Dynasty from a collection of loosely related repos into an orchestrated product ecosystem with specialized agents, a growth roadmap, and a local initiative tracker.

### Directory Cleanup
1. **Archived stale files** — moved `pd_master.db`, `gameplay.db`, `discord.log`, `wpa_data.csv`, `PROJECT_PLAN.json`, `pr-card-run.md` to `.archive/`
2. **Deleted dead projects** — `gameplay-webapp/` (superseded by multi-league project, remote up to date) and `gameplay-website/` (no git repo, abandoned predecessor)
3. **Archived `database-checks/`** — one-off SQL scripts from June 2025 moved to `.archive/`
4. **Created `.archive/` directory** — `dev-storage/` was previously misused for archival (it's a Docker shared volume mount)

### Ecosystem Documentation
5. **Created parent `CLAUDE.md`** — full ecosystem map with architecture diagram, deployment topology, "which repo do I change?" routing table, cross-project conventions
6. **Created `ROADMAP.md`** — 3-phase growth roadmap (Foundation → Engagement → Growth) with specific initiatives, sizing, impact categories, and engagement metrics framework. Grounded in actual Gitea issue numbers.
7. **Fixed SQLite references** — updated all docs and agent definitions to reflect PostgreSQL (both prod and dev are now PG)

### Agent Architecture
8. **Created 5 specialized agents** in `~/.claude/agents/`:
   - `pd-database` (Opus) — Product Owner for Database API
   - `pd-discord` (Opus) — Product Owner for Discord Bot
   - `pd-cards` (Opus) — Product Owner for Card Pipeline
   - `pd-growth` (Opus) — Growth Product Owner (cross-project strategy)
   - `pd-ops` (Sonnet) — Release operations (merge workflow, deploys, process)
9. **PO agent hierarchy** — Opus agents decide what to build, `pd-ops` ensures it ships correctly, implementation delegated to existing `engineer`/`issue-worker`/`swarm-coder` agents

### PR Backlog Clearance
10. **Merged 21 PRs across 3 repos:**
    - Card-creation: 8 PRs (#29 security, #38, #39, #37, #35, #40, #43, #45 — bug fixes)
    - Discord: 9 PRs (#86, #84, #85, #89 crash fixes; #104 dead code cleanup; #105 duplicate file removal; #106 gameplay fixes; #107 check-in + paperdex)
    - Database: 2 PRs (#103 paperdex timeout, #95 benchmark script)
11. **Closed 15 PRs:**
    - Card-creation: 2 superseded (#42, #44 — covered by #29)
    - Discord: 13 stale (#61-#71 targeting dead `next-release` branch, #96 superseded by individual WP PRs)
12. **Re-implemented 11 fixes fresh** — the stale Discord PRs had unrebaseable conflicts from a scouting refactor; dispatched issue-worker agents to re-implement against current `main` in 4 batched PRs
13. **PR reviewer caught 2 real bugs** — rarity param silently ignored by API (#106), None crash in paperdex dupe detection (#107). Both fixed before merge.

### Skill & Tooling Upgrades
14. **Upgraded `/paper-dynasty` skill** — added ecosystem dashboard script, growth roadmap reference, specialized agent dispatch table, initiative tracker documentation
15. **Created `ecosystem_status.sh`** — cross-repo dashboard pulling issues/PRs/commits from all 6 Gitea repos
16. **Built `pd-plan` initiative tracker** — SQLite-based CLI at `~/.claude/skills/paper-dynasty/plan/cli.py` with 17 seeded initiatives, activity logging, `--json` output, filtering by phase/repo/status/impact

### Issues Created
17. **6 new Gitea issues:**
    - Database #122: Remove legacy SQLite compatibility code
    - Database #123: Update database CLAUDE.md
    - Database #124: Rewrite skill scripts to use API instead of SQLite
    - Discord #108: Resolve ruff pre-commit hook vs pre-existing violations

## Decisions

### PO Agent Model: Opus for Strategy, Sonnet for Execution
PD-specific agents run on Opus for strategic reasoning (backlog prioritization, design decisions, cross-project coordination). Implementation and ops use Sonnet. This avoids wasting Opus tokens on mechanical work while ensuring product decisions get deep reasoning.

### "Refractor" Naming for Card Progression
The card evolution system (internal codename "Evolution") is renamed to **Refractor** for all user-facing surfaces. Inspired by Topps Chrome card collecting terminology. Tier names: Base Chrome → Refractor → Gold Refractor → Superfractor. Chosen over alternatives like Breakout, Grade, Press, Callup after competitive analysis across 15+ games (MLB The Show, NBA 2K, Marvel Snap, etc.). "Evolution" was already used by NBA 2K and EA FC.

### next-release Branch Pattern Retired
All work now targets `main` directly. The `next-release` staging branch pattern is no longer used. This simplified the PR backlog significantly — 12 stale PRs targeting `next-release` were closed and re-implemented against `main`.

### PR Review Process: Mandatory pr-reviewer Gate
PRs must always go through a `pr-reviewer` agent before merging. Cal corrected the workflow when auto-approving was attempted. The reviewer caught 2 real bugs this session.

### Two-User Auth for Merges
Claude-authored PRs → cal approves. Cal-authored PRs → Claude approves. Both tokens stored in `~/.claude/secrets/`. Documented in `pd-ops` agent.

### Local SQLite for Initiative Tracking
Chose a local SQLite database over Gitea project boards (no API in Gitea 1.22.6), n8n datatables (external dependency), or structured JSON (merge conflict risk). SQLite gives full schema control, instant queries, no external deps, and agent-friendly access.

### dev-storage is Docker Volume, Not Archive
`dev-storage/` is a mapped volume for local Docker containers — do not use for archival. Use `.archive/` instead.

## Follow-Up

| Item | Priority | Notes |
|---|---|---|
| Card-creation: 11 PRs need Cal's review | High | Logic/balance changes: #36, #34, #33, #41, #46, #49, #48, #47, #30, #31, #32 |
| Discord #87: Refractor rename before merge | High | Rename cog, command group, tier badges |
| Discord #88: Tier badge approach rethink | Medium | Comment left — reconsider API call per embed |
| Discord #73: Ranked mode merge | Medium | Hold until after cleanup, needs rebase |
| Discord #108: Ruff pre-commit resolution | Medium | Options documented in issue |
| Database #122-124: SQLite cleanup | Medium | 3 issues created |
| Database #84, #99, #96: Rebase onto correct branches | Low | Evolution migration + next-release PRs |
| Delete `next-release` branch in Discord repo | Low | Pattern retired |
| Rotate secrets exposed in git history | High | PR #29 (card-creation) removed hardcoded PD API token and Supabase JWT — both need rotation |
