Upload files to "Planning"

2026-09-10 00:27:28 +00:00
commit 6c7d31371e
3 changed files with 553 additions and 0 deletions
@@ -0,0 +1,231 @@
 # Corporate Ladder Game — Big Picture Brainstorm
 This document captures the full vision for the game: everything on the table, from
 the near-term prototype through the long-term dream version. Not everything here
 gets built at once — this is the idea space the architecture needs to be able to
 grow into.
 ## Core Concept
 A browser-based career simulation game. The player starts at the bottom of an
 organization (e.g. the mailroom in a modern corporate setting) and plays through
 turns (a day or a week each), making choices that shape their career, finances,
 relationships, and reputation.
 It is **not** a pure narrative experience — there is real scoring, real numeric
 state, and real progress to track. It is also not a spreadsheet optimization
 game — the numbers exist to give the story stakes and a scoreboard, not to reward
 min-maxing. The target feel is **light and fun**, with enough rigor underneath
 that choices matter.
 ## Gameplay Pillars
 ### 1. Choose-Your-Own-Adventure + Simulation Hybrid
 - Early version: scripted choices. Each turn presents a small, fixed set of
  options (e.g. 2–3 actions).
 - Later version: free-text player input. The player types what they want to do
  in their own words, and an AI layer interprets that into a game action (e.g.
  "I stay late and grind it out" → *hard work* action; "I look for a way to
  duck out early" → *shortcut* action). The AI can also generate more colorful,
  varied dialogue and flavor text around the outcome.
 - Underneath both modes, the same numeric engine runs: money, stats,
  relationships, skills.
 ### 2. Multidimensional Success
 - Title/promotion is one axis of success, not the only one.
 - Other axes: skills learned, relationships built, reputation, personal
  satisfaction.
 - Strategic depth: a player might deliberately stay at a lower level longer to
  build skills or relationships before pushing for a promotion, rather than
  always rushing upward. Rushing every promotion should be able to create real
  downstream problems (skill gaps, thin relationships) — but this should
  emerge from the choices available, not from punishing math.
 ### 3. Skills as Gates, Not Just Flavor
 - Skills (e.g. negotiation, technical ability) are tracked stats.
 - Low skill in an area can lock out certain choices entirely, or make them
  much riskier.
 - Skills grow **organically**, as a side effect of taking related actions and
  events — not through a dedicated "go train" menu. The goal is to avoid a
  grindy, click-here-click-there feel. Growth should feel like something that
  happens to you as a consequence of living the story, not a chore you manage.
 ### 4. Characters with Real Weight
 - Every character has flavor description text (appearance, personality quirks
  — tall, charismatic, particularly attractive, gruff, etc.) purely for color.
 - Underneath, characters carry real relationship stats toward the player:
  - How much they **like** you
  - How much they **fear** you
  - How much they're willing to **help** you
 - A darker mechanic: leverage/pressure material — not necessarily
  "blackmail" in the extreme sense, but things a character wouldn't want to
  come out, which the player can use as a lever to influence behavior. This
  gives the player a second currency beyond money: information and
  reputation as power.
 - Influence is central to gameplay — persuading a boss to let you leave
  early, or a coworker to cover your shift, might work because you've been
  kind to them (they like you) or because you've been intimidating (they fear
  you). Different relationship paths should lead to similar outcomes through
  different means.
 - Characters should have extensive, distinct backstories, so that even when
  the underlying stat skeleton is the same across playthroughs, individual
  characters feel different and memorable each time.
 ### 5. Random Events, Built to Scale
 - The initial version should have a small, tightly scoped set of random
  events.
 - Critically, the underlying data structures for events (and everything else)
  should be built so that adding new events later is just adding new data —
  never a rewrite of game logic. Events and choices should be treated as data
  the engine reads generically, not hardcoded logic scattered through the
  codebase.
 ### 6. Soft Failure, Not Game Over
 - No hard "you lose" state.
 - Failure is a spiral of **suffering and reduced options**, not a dead end:
  - Bankruptcy might force taking out a loan.
  - A demoted or struggling player might have to do menial work for, or take
    orders from, someone they used to outrank.
  - The player can always keep pushing to climb back out, at a cost.
 - A player can choose to walk away because it's "too painful," but the game
  itself doesn't force an ending on them.
 - This keeps players engaged in the story even at rock bottom, and it opens up
  strong narrative beats — being humbled by a character you were dismissive of
  earlier should hit differently than being humbled by a stranger.
 ### 7. Open-Ended Pacing with a Natural Ceiling
 - No fixed turn count or forced ending.
 - The game naturally self-limits: once a player becomes, say, company
  president with influence over everyone, there's nowhere higher to climb —
  the sandbox is exhausted, not because a clock ran out.
 - The "ending," whenever a player stops, is the same regardless of how far
  they got: a **career retrospective** — what you did, what you didn't do,
  key relationships, notable moments (and eventually notable
  images/videos), presented uniformly whether the player "won" or "lost."
 ### 8. Single Player Only
 - No multiplayer, no competitive syncing across players. This simplifies a
  large amount of design and technical complexity and keeps the focus on the
  player's individual story.
 ### 9. Infinite Themes via Data-Driven Design
 This is one of the most important architectural commitments:
 - The game engine, mechanics, and code should **never need to change** to
  support a new setting or theme.
 - Theme is purely a data layer: character archetypes, job titles, event
  flavor text, tone, and even the *boundaries of allowed content* are all
  swappable data/content packs.
 - Example themes: modern corporate (primary/default), auto manufacturing,
  high-tech startup, Wild West, medieval guild, sci-fi/Star Trek-style,
  textile mill, or even a kid-friendly "lemonade stand" version for younger
  players.
 - Content packs also control maturity level: a kid-friendly theme keeps
  everything light, while a more adult theme could unlock sharper-edged
  mechanics (like real blackmail-style pressure points) — the mechanics
  underneath stay identical; only the data changes what's permissible and how
  it's flavored.
 - Replayability also comes from randomized competitive density — e.g. one
  playthrough might have five rivals competing for the same mailroom
  promotion, another might have just one. Same mechanics, very different felt
  experience.
 ### 10. AI Integration (Long-Term)
 - **Dialogue and interpretation**: free-text player input gets interpreted by
  an AI into structured game actions, and the AI generates more natural,
  varied dialogue for NPCs and outcomes.
 - **Stateless inference architecture**: this is an important technical
  decision. The inference engine itself (e.g. a local Llama-class model) is
  stateless — it's a pure function that takes an assembled prompt and returns
  a response. It does not maintain any memory or state of its own.
  - All state — player situation, history, current stats, active theme/genre,
    scene context — lives at the **application/game engine layer**.
  - The game engine is responsible for assembling the right context and
    building the prompt fresh on every call.
  - This keeps the game portable across different inference backends and
    keeps behavior predictable and debuggable.
 - **Configurable inference endpoint**: rather than the game hosting or
  depending on a specific AI service, the configuration should include a
  pointer to an inference engine (e.g. a local Llama-equivalent server) that
  the user points at themselves. The core game should never require Jesse to
  run or pay for a hosted inference service.
 - **Generated media (further out)**: AI-generated images or short video
  vignettes for big narrative payoff moments — e.g. an award ceremony
  producing a generated image of the player receiving a medal, or a short
  video vignette for a major win. This is explicitly a "big picture" /
  aspirational feature, well downstream of the prototype.
 ### 11. Logging & Feedback, Built In From Day One
 This should exist even before any AI is involved, starting with the very first
 scripted-only prototype:
 - **Full instrumentation**: every player action and its resulting effect
  should be captured/logged from turn one. This serves two purposes:
  1. Playtesting research — understanding what players actually do and want.
  2. Future AI tuning — once AI-driven dialogue/interpretation exists, having
     a baseline of real scripted interactions to compare against.
 - **In-game feedback widget**: a persistent "feedback to game designer"
  element on the turn screen (can be optionally hidden later once trust in
  the game is established, but visible by default early on):
  - Thumbs up / thumbs down / neutral rating per turn.
  - Optional free-text comment field.
  - If the player doesn't interact with it, nothing happens — it's fully
    passive/optional.
  - This is also the natural place to capture "I wanted to do something that
    wasn't an available option" feedback, which is gold for identifying where
    the scripted choice set is too narrow.
 - **Separate export stream**: feedback/logging data is captured as its own
  independent export, distinct from the game save file. It's meant for
  Jesse's review and analysis, not for reloading into a playthrough.
 ## Technical Direction (Big Picture)
 - **Browser-based, client-heavy**: strong preference for a simple tech stack
  that runs entirely client-side (HTML/CSS/JavaScript), with no heavy backend
  services required. Ideally the only server-side requirement (if any) is
  serving the static page.
 - **Saves**: browser local storage as the default/primary save mechanism, with
  an explicit export/import (save-to-file) option so an accidental cache
  clear or browser crash doesn't destroy a career in progress.
 - **Data schema**: characters and events should carry tags/flags (e.g.
  department, role type like rival/mentor/peer for characters; stage/level
  and which stats are affected for events) so the engine can query and filter
  generically, instead of hardcoding per-entity logic.
 - **Extensibility as a first-class constraint**: every system (events,
  characters, themes) should be structured as data the engine reads, so that
  adding new content later doesn't require reworking the engine.
 ## Relationship to Jesse's Other Project
 Jesse is separately building an **interactive story** project that is purely
 narrative-focused, with no game mechanics or scoring layer. This corporate
 ladder game is explicitly the opposite emphasis: it must have real scoring and
 measurable progress, not just storytelling. There may be shared code or
 techniques between the two (especially around AI-driven dialogue/story
 generation), but they are distinct projects with distinct goals.
 ## Open Questions / Things to Revisit Later
 - What's the full list of core character fields beyond name, role/title,
  relationship stats (like/fear/help), and flavor description? (Tags for
  department and role-type like rival/mentor/peer were agreed as a good
  addition.)
 - What's the full list of core event fields beyond description and effects?
  (Tags for stage/level and affected stats were agreed as a good addition.)
 - How exactly does a player move between tiers/levels once promotion is
  introduced (post-MVP)?
 - What does the "career retrospective" screen actually look like/contain in
  detail?
 - How should the feedback widget's visibility toggle work, and when should it
  default to hidden vs. shown?
@@ -0,0 +1,151 @@
 # Corporate Ladder Game — Minimum Viable Prototype (MVP) Spec
 This is the scope for the **first playable version**. It intentionally leaves
 out AI, promotion, multiple themes, and generated media — but it must be built
 on data structures that support all of that later without a rewrite.
 ## Goal of This Version
 Prove out the core turn loop: scripted choices → stat/relationship/money
 changes → open-ended replayable play → an ending retrospective whenever the
 player chooses to stop. Validate that the loop is fun in its simplest possible
 form before adding complexity.
 ## Scope: What's IN
 - **Single setting/theme**: modern corporate office, mailroom level only.
 - **Single tier**: no promotion mechanic yet. The player stays in the mailroom
  and can keep playing indefinitely.
 - **Turns**: each turn represents a day or a week (pick one for the
  prototype — day is likely simpler to reason about first).
 - **Two characters**:
  - One boss (authority figure — approves/denies requests, can make life
    easier or harder).
  - One coworker rival (peer-level, competing for the same eventual
    promotion, can help or hinder).
  - Both have: name, flavor description (personality/appearance color text),
    and the three relationship stats (likes-you, fears-you, wants-to-help-you)
    toward the player.
  - Both have tags for role type (e.g. `boss`, `rival`) so later additions of
    more characters (mentor, peer, etc.) slot into the same schema.
 - **Player stats**:
  - Money (with basic income and basic recurring costs).
  - At least one skill (e.g. negotiation) that can grow organically from
    relevant choices and can gate at least one choice option.
  - The three relationship-facing stats as tracked per-character (not global).
 - **Choices per turn**: a small, fixed set (2–3 scripted options), each with
  a clear immediate effect on stats/relationships/money. No free-text input
  yet — that's a later phase.
 - **Random events**: a very small number (a handful) of simple scripted
  events that can occasionally fire instead of, or alongside, a normal turn's
  choice set. Kept minimal, but implemented through the same generic
  event-data structure the full game will use later (not a special-cased
  hack).
 - **Soft failure state**: at least one basic version of the "soft failure"
  loop — e.g. if money goes negative, the player is offered a demeaning
  option (take a loan, do a favor for the rival) rather than the game ending.
 - **Open-ended play**: no turn cap. The player can keep taking mailroom turns
  for as long as they want.
 - **Ending / retrospective**: a simple end-of-session summary screen the
  player can trigger (e.g. a "wrap up my career" action, or reaching it when
  they close out), showing: final money, final relationship stats per
  character, and a short list of notable moments/events that occurred. This
  screen should look the same in structure whether the player did "well" or
  "poorly" — it's a summary, not a win/lose screen.
 - **Save system**:
  - Browser local storage as the live/default save.
  - Explicit export-to-file and import-from-file so progress survives a
    cleared cache or browser crash.
 - **Feedback & logging system** (present from turn one, even without AI):
  - A persistent, always-visible-by-default feedback widget on the turn
    screen: thumbs up / thumbs down / neutral, plus an optional free-text
    comment box. No action required — ignoring it does nothing.
  - Every player action and its resulting effects are logged.
  - Feedback and logs are captured in their own **separate export**, distinct
    from the game save file.
 - **Data-driven structure for everything above**: characters, events, and
  choices should all be represented as data (e.g. JSON-like structures) that
  a generic engine reads and processes — not hardcoded if/else logic per
  character or event. This is the seed of the "themes are just data" and
  "events are just data" architecture from the big-picture vision.
 ## Scope: What's explicitly OUT (for now)
 - No promotion or second tier.
 - No free-text/AI-driven input or dialogue.
 - No AI-generated images or video.
 - No multiple themes/settings (mailroom/corporate only).
 - No multiplayer (never planned — out of scope permanently, not just for
  MVP).
 - No complex leverage/blackmail system yet — at most a placeholder field on
  characters that isn't deeply used yet.
 - No account system — local storage + file export/import only.
 - No dedicated "training" or skill-grinding menu — skill growth stays
  incidental to choices.
 ## Tech Stack for MVP
 - Fully client-side: HTML, CSS, and JavaScript, runnable directly in a
  browser with no required backend.
 - If any server component exists at all, it should be limited to serving
  static files — no game logic server-side.
 - No external dependencies beyond what's needed to keep the app simple and
  self-contained (avoid heavy frameworks unless there's a clear reason).
 - Game state, character data, and event data should be structured as plain
  data objects/files so they can later be swapped or extended (new themes,
  more events, more characters) without touching engine code.
 ## Suggested Data Shape (Starting Point)
 This isn't final, but gives a concrete starting schema for the MVP:
 **Character**
 - `id`
 - `name`
 - `role_type` (tag, e.g. `boss`, `rival`)
 - `description` (flavor text)
 - `likes_you` (number)
 - `fears_you` (number)
 - `wants_to_help_you` (number)
 **Event / Turn Choice**
 - `id`
 - `stage_tag` (e.g. `mailroom`) — for future filtering by level
 - `description` (flavor text shown to player)
 - `options[]`, each with:
  - `label`
  - `effects` (changes to money, skill, relationship stats)
  - `requires` (optional skill/stat gate)
 **Player State**
 - `money`
 - `skills` (map of skill name → value)
 - `relationships` (map of character id → stat object)
 - `history` (log of turns taken, for the retrospective screen)
 **Feedback Log Entry** (separate export, not part of save)
 - `turn_id`
 - `action_taken`
 - `rating` (up / down / neutral / none)
 - `comment` (optional text)
 - `desired_but_unavailable_action` (optional text, if the player wanted
  something not offered)
 ## Definition of Done for MVP
 The prototype is "done" when a player can:
 1. Start a new game in the mailroom.
 2. Take repeated turns, choosing from a small set of scripted options each
   time, watching money, skill, and relationship stats change.
 3. Occasionally encounter one of the small set of random events.
 4. Hit a soft-failure scenario (e.g. run out of money) and be offered a
   demeaning-but-survivable option instead of a game over.
 5. Leave optional feedback (thumbs up/down/neutral + comment) on any turn.
 6. Save and reload their game via local storage, and export/import via file.
 7. Trigger an end-of-session retrospective screen summarizing their run.
 8. Keep playing indefinitely if they choose to, with no forced ending.
 All of this should be built on data structures (for characters, events, and
 choices) that will support adding new events, new characters, a promotion
 tier, and eventually new themes — without needing to rewrite the core engine.
@@ -0,0 +1,171 @@
 # Claude Code Build Prompt — Corporate Ladder Game MVP
 Copy everything below the line into Claude Code as your starting prompt.
 ---
 I want to build a browser-based career simulation game called (working title)
 "Corporate Ladder." This is a **minimum viable prototype** — please treat this
 as the first phase of a larger project, and follow a research/plan-first
 approach before writing code: propose a file/folder structure and data schema
 first, surface any open questions, and get my explicit go-ahead before you
 start implementing.
 ## Core Concept
 A turn-based career sim. The player starts in the mailroom of a modern
 corporate office. Each turn (treat a turn as one day), the player is shown a
 short scripted scenario and picks from 2–3 choices. Choices affect the
 player's money, a skill stat, and relationship stats with two NPCs (a boss and
 a coworker rival). The game has no fixed length — the player can keep taking
 turns indefinitely — and at any point can trigger a "wrap up my career"
 retrospective screen summarizing what happened.
 This is explicitly a **prototype/foundation**, not the full game. The most
 important requirement is that everything be **data-driven**: characters,
 events, and choices should live in data structures (JSON or equivalent) that
 a generic engine reads and processes. Do not hardcode character-specific or
 event-specific logic in the engine — the engine should not need to change to
 add a new character or event, and eventually should not need to change to
 support an entirely different theme/setting (e.g. Wild West instead of
 corporate office). Please design the schema with that future flexibility in
 mind, even though this build only needs to ship the corporate/mailroom
 content.
 ## Tech Stack
 - Fully client-side: plain HTML, CSS, and JavaScript. No required backend —
  it should be able to run by opening a static HTML file (or via a trivial
  static file server for local dev).
 - Keep dependencies minimal. Avoid heavy frameworks unless you think there's
  a strong reason — I'd rather this stay simple and easy to reason about.
 - No database, no accounts. State lives client-side.
 ## Required Features for This Build
 ### 1. Core Turn Loop
 - Player starts a new game in the mailroom with starting values for money,
  one skill (e.g. "negotiation"), and neutral relationship stats with the two
  NPCs.
 - Each turn presents a short text scenario and 2–3 choices.
 - Choices apply effects to money / skill / relationship stats.
 - Some choices may require a minimum skill level to be available (a simple
  gating mechanism).
 - No fixed number of turns — the player can keep playing.
 ### 2. Two NPCs
 - A boss and a coworker rival.
 - Each has: name, a short flavor description (personality/appearance text,
  purely for color), a role-type tag (`boss` / `rival`), and three numeric
  relationship stats toward the player: `likes_you`, `fears_you`,
  `wants_to_help_you`.
 - Design the character schema so additional role types (e.g. `mentor`,
  `peer`) could be added later without changing engine code.
 ### 3. Random Events
 - Implement a small handful (4–6) of simple random events using the *same*
  data structure as regular scripted turns — i.e. an event is just another
  entry in the event/turn data with a tag marking it as a random event and
  some trigger condition (e.g. a probability or a stat threshold). Do not
  special-case these in the engine logic.
 ### 4. Soft Failure State
 - If money drops below zero (or some defined threshold), don't end the game.
  Instead, surface a distinct "hard times" branch of choices — e.g. take out
  a loan (debt that must be paid down over time) or do a demeaning favor for
  the rival (which affects relationship stats and possibly unlocks money).
  The player should be able to work their way back out.
 ### 5. Retrospective / Ending Screen
 - A "wrap up my career" action the player can take at any time.
 - Shows: final money, final relationship stats with each NPC, and a short
  list of notable moments/events from their playthrough (pull from a simple
  history log kept during play).
 - This screen's structure should be the same regardless of how the
  playthrough went — it's a summary, not a win/lose screen.
 ### 6. Save System
 - Auto-save to browser local storage as the player progresses.
 - An explicit "Export Save" button that downloads the current game state as a
  JSON file, and an "Import Save" option to load one back in.
 ### 7. Feedback & Logging System
 - On every turn screen, include a small, always-visible (for now) feedback
  widget: thumbs up / thumbs down / neutral buttons, plus an optional
  free-text comment box. The player is never required to interact with it.
 - Also include an optional field where the player can note "something I
  wanted to do that wasn't an option here."
 - Log every turn's chosen action and its effects, along with any feedback
  given, to a **separate log** that is exportable independently from the game
  save (a separate "Export Feedback Log" button/JSON file). This should not
  be mixed into the save-game file.
 ## Data Schema (Starting Point — feel free to refine, but keep me in the
 loop on changes)
 ```
 Character:
  id: string
  name: string
  role_type: string        // e.g. "boss", "rival"
  description: string      // flavor text
  likes_you: number
  fears_you: number
  wants_to_help_you: number
 TurnEvent:
  id: string
  stage_tag: string         // e.g. "mailroom" (for future level filtering)
  is_random_event: boolean
  description: string
  options: [
    {
      label: string
      effects: { money?: number, skills?: { [name]: number },
                 relationships?: { [character_id]: { likes_you?: number,
                 fears_you?: number, wants_to_help_you?: number } } }
      requires?: { skill: string, min: number }
    }
  ]
 PlayerState:
  money: number
  skills: { [name]: number }
  relationships: { [character_id]: { likes_you, fears_you,
    wants_to_help_you } }
  history: [ { turn_id, event_id, choice_label, timestamp } ]
 FeedbackLogEntry:
  turn_id: string
  action_taken: string
  rating: "up" | "down" | "neutral" | null
  comment?: string
  desired_but_unavailable_action?: string
 ```
 ## What NOT to Build Yet
 - No promotion mechanic or second tier/level — mailroom only for this build.
 - No AI/LLM integration of any kind yet — this build is fully scripted.
 - No AI-generated images or video.
 - No multiple themes/settings — corporate/mailroom only, but keep the schema
  theme-agnostic in spirit (i.e. don't bake "mailroom" assumptions into the
  engine logic itself, keep it in the data).
 - No multiplayer — this is a permanent design decision, not just an MVP gap.
 - No account system or server-side persistence.
 ## Process
 Please:
 1. Propose a project structure and confirm the data schema with me before
   writing implementation code.
 2. Flag any open questions (e.g. exact starting stat values, exact effect
   magnitudes) rather than guessing silently — reasonable defaults are fine
   but call them out.
 3. Build incrementally, and let's check in after the core turn loop works
   before layering on the feedback system, save/export, and random events.
 4. Keep commits small and incremental rather than one giant commit at the
   end.
 Let me know once you've reviewed this and have a proposed structure, or if
 you have clarifying questions before we start.