TheLadder/Planning/02-corporate-ladder-mvp-spec.md

# 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.