gogobee/gogobee_design_index.md

GogoBee Design Document Index

Read this first. Then read the docs relevant to your work, in dependency order.

All docs in this index live at the repo root (/home/reala-misaki/git/gogobee/*.md). If you're starting an implementation session, read every entry below before opening code — many systems cross-reference each other and reading one doc in isolation has historically led to under-scoped work.

---

The corpus

Doc	Scope	Status
gogobee_dnd_design_doc.md	v1.0 vision: D&D character system, classes, races, ability scores, leveling, combat resolution, abilities, equipment slots, monsters, skill checks, rest, onboarding/migration, NPC integration	Vision; superseded for implementation by v1.1
gogobee_dnd_design_doc_v1.1.md	v1.0 reconciled against actual codebase: real schema, archetype names, layered (not replacement) approach, smaller phase plan	Implementation source-of-truth
gogobee_dnd_session_summary.md	What's actually been built so far across phases 1-7 + audit fixes + flavor wiring	Living record
gogobee_design_index.md	This file	—

System docs (companions to v1.0/v1.1)

Doc	Owns	Hard dependencies
gogobee_action_economy_death.md	Turn-based action economy (Action/Bonus/Reaction/Movement), death saves, hospital recovery	None — foundation
gogobee_equipment_appendix.md	Weapon damage dice, armor AC tables, magic item templates, ammo, ComputeAC helper	Action economy
gogobee_spell_system.md	79 spells (cantrip–L5), spell slots, concentration, three casters (Mage/Cleric/Ranger), spell save DC	Action economy, equipment (component pouch / focus)
gogobee_subclass_system.md	15 subclasses (3 per class × 5 classes), L5 selection prompt, L5/7/10/15 abilities	Action economy, spells (Arcane Trickster)
gogobee_dungeon_zones.md	10 named zones, TwinBee GM persona w/ Mood Score, 5 room types, named bosses with multi-phase mechanics, tier gating	Combat (any), monsters, equipment (loot), spells (boss casters)
gogobee_expedition_system.md	Multi-day persistent expeditions, day cycle (06:00 brief / 21:00 recap), threat clock, supply system, camp tiers, extraction, siege mode	Zones (zones get wrapped), action economy (combat events), resources
gogobee_resource_combat_integration.md	Harvest nodes per zone, combat-as-event (room/interrupt/patrol/ambush), zone-specific loot tables	Zones, expedition, action economy, equipment
gogobee_housing_babysitter.md	Housing tiers 0-6 (rent + mortgage), 13 property upgrades, FRED ARM rate integration, Pastel babysitter NPC	Economy (existing euro_balances), pets (Pastel feeds them)
gogobee_pet_system.md	30 named pets, tier 1-3 + Legendary, Ranger Pet Bond (5 tiers), happiness, pet leveling	Subclass (Ranger), housing (pet capacity per tier)
gogobee_remaining_systems.md	Skill Proficiency selection, Arena polish, Misty/Arina quest system, Pete Bot broadcasts, Economy by tier, Crafting recipes	Various; the catch-all

Reading order by intent

Implementing combat changes: dnd_design_doc_v1.1 → action_economy_death → equipment_appendix → spell_system → subclass_system.

Implementing world content (zones, dungeons): dnd_design_doc_v1.1 → dungeon_zones → expedition_system → resource_combat_integration → relevant flavor files in internal/flavor/.

Implementing economy/housing/pets/NPCs: dnd_design_doc_v1.1 → housing_babysitter → pet_system → remaining_systems (for quests) → internal/flavor/twinbee_npc_flavor.go and twinbee_housing_flavor.go.

Onboarding to the project cold: all of v1.1 → this index → dnd_session_summary.md → then deep-dive into the system you're touching.

Cross-reference graph (one-line summary)

                        dnd_design_doc / v1.1 (root)
                                |
          ┌─────────────────────┼──────────────────────┐
          ↓                     ↓                      ↓
  action_economy_death   dungeon_zones          housing_babysitter
          │                     │                      │
          ├──→ equipment        ├──→ expedition        └──→ pet_system
          ├──→ spell_system     │       │                       │
          ├──→ subclass         │       └──→ resource_combat    │
          │       │             │                ↑              │
          │       └─────────────┴────────────────┘              │
          │                                                     │
          └─────────────→ remaining_systems ←───────────────────┘
                          (quests, arena, Pete bot, crafting,
                           skill profs, economy by tier)

Flavor file locations

All flavor lives in internal/flavor/ (not at the repo root). These files have DO NOT REWRITE headers — never edit content; new pools go in new files only.

• twinbee_gm_flavor.go — TwinBee GM narration: room entries per zone, boss entries per named boss, combat outcomes, nat 20/1, level up, rest, traps, conditions, saves, taunts/compliments
• twinbee_expedition_flavor.go — Morning briefings (Day 1/3/7/14/21), evening recaps, camp, supply warnings, threat clock states, per-zone hazards (tides, time distortion, awareness pulses, portal destabilization), extraction, milestones
• twinbee_resource_flavor.go — Harvest pools per type (forage, mine, scavenge, essence, commune, fish), per-zone harvest variants, fishing per-zone, loot drops by rarity, patrol encounters
• twinbee_npc_flavor.go — Misty + Arina + Pete pools (greetings, skill checks, quests, trust/favorite tiers, Pete broadcasts including patch notes)
• twinbee_housing_flavor.go — Thom Krooke (rent, buy, mortgage, default, eviction, passive income), Pastel (hire, fire, level notes 1-5, missed tasks, deliveries, gifts, returns), home arrival, long rest at home, property upgrades (Workshop, Herb Garden, Vault, Trophy Room, Expedition Outpost)
• pick.go — flavor.Pick(pool []string) string helper

Discipline

• Adding a new system: add a new design doc under gogobee_<system>_name.md. Update this index in the same change.
• Updating a system: prefer adding a Section X.Y — addendum rather than rewriting prose. The agents read these docs verbatim.
• Removing a system: mark the doc as deprecated in this index; don't delete unless the entire system is gone.
• Cross-references in design docs: every doc should declare its companions in its header (> Companion to: ...). The dnd_design v1.0 doc didn't, which is why a session in 2026 spent six hours building 20% of the spec before noticing the rest existed.