commit 6c7d31371eab4faa2651bbcdaac06e6a57c5d8c0 Author: Jesse.Markowitz Date: Thu Sep 10 00:27:28 2026 +0000 Upload files to "Planning" diff --git a/Planning/01-corporate-ladder-brainstorm.md b/Planning/01-corporate-ladder-brainstorm.md new file mode 100644 index 0000000..2403dc8 --- /dev/null +++ b/Planning/01-corporate-ladder-brainstorm.md @@ -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? diff --git a/Planning/02-corporate-ladder-mvp-spec.md b/Planning/02-corporate-ladder-mvp-spec.md new file mode 100644 index 0000000..e4a083f --- /dev/null +++ b/Planning/02-corporate-ladder-mvp-spec.md @@ -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. diff --git a/Planning/03-claude-code-build-prompt.md b/Planning/03-claude-code-build-prompt.md new file mode 100644 index 0000000..1845b63 --- /dev/null +++ b/Planning/03-claude-code-build-prompt.md @@ -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.