# Idlegame — M1 Vertical Slice Plan (handoff artifact for superpowers)

> **How to use this file:** the M1 brainstorm is complete; everything below is locked (approved by ginnoir 2026-06-11). Hand this plan to superpowers for execution. Tasks are grouped into **four phased PR batches** plus a **Phase 0 vault gate** for story content. Each phase ends at a browser-playable checkpoint. One tool per branch; everything lands via PR.
>
> **Canonical location:** `docs/plans/2026-06-11-m1-vertical-slice.md` in the working dir.

## Context

M0 is complete (2026-06-11). The repo ships a walking skeleton: one resource, one timed action, fixed-timestep tick loop with offline catch-up, versioned saves (v1, reject-on-mismatch), Zustand bridge, minimal React shell, CI + internal playtest deploy at `https://idlegame.ginnoir.com/`. Vault notes exist: `Idlegame/GDD.md`, `Idlegame/Decisions.md`, `Idlegame/Story/Outline.md` (beat skeleton placeholder — prose TBD).

**M1 scope:** turn the skeleton into the first playable vertical slice — one short story arc through the first prestige reset, with a meaningful branching choice, one automation unlock, offline progress, and save/load (including migration scaffolding). Ten Gitea issues (#3–#12) under milestone **M1 Vertical Slice** map to this plan.

**Execution mode (locked):** phased PR batches with playable checkpoints after each merge — not one mega-run, not one-PR-per-issue.

## M1 success criteria

A player on the internal playtest build can:

1. Queue multiple timed actions and watch resources accrue with costs/unlocks respected.
2. Read story passages and make a branching choice where routes A and B produce visibly different outcomes (flags, resources, or event-log entries).
3. Unlock automation for at least one action after completing it manually once.
4. Finish the opening arc and trigger the first prestige reset, retaining knowledge for catch-up on the next run.
5. Reload, export/import a save, and play comfortably on a phone viewport.

## Locked M1 decisions (brainstorm, 2026-06-11)

| Decision | Choice |
|---|---|
| Phase structure | **Approach 1 — playable-first ladder:** 4 PRs + Phase 0 vault work |
| Story timing | Phase 0 outline runs **in parallel** with PR1–2; stub prose proves branch mechanics; **ginnoir review gate** before PR3 merges real content |
| Stub content | Placeholder names/prose allowed in PR1–2; replaced entirely in PR3 |
| Prestige depth | First reset only — within-layer catch-up (knowledge flags, fast-forward); **no new mechanics between layers** (post-M1) |
| Save version | Bump to v2 in PR4 when story/queue/automation/prestige fields land; v1→v2 migration required |
| Balance | Tunable constants in content defs; notes filed in vault during T4.3 |

Design pillars unchanged from M0 — see `Idlegame/GDD.md` and `docs/plans/2026-06-11-m0-bootstrap.md` §Locked design pillars.

## Starting codebase state

```
src/engine/     game.ts (single active action, no queue)
                tickLoop.ts (accumulator + maxTicks cap)
                save.ts (SAVE_VERSION=1, reject mismatch)
                num.ts
src/content/    one resource (gold), one action (forage)
src/state/      runtime (RAF loop), persistence (idb + localStorage)
src/ui/         ResourceBar, ActionPanel, EventLog stubs
```

Architecture boundaries unchanged — see `docs/architecture.md`.

## Phase map

| Phase | Branch | Closes Gitea | Playable checkpoint |
|---|---|---|---|
| **0** | *(vault, no PR)* | prep for #11 | Opening arc beats outlined; prose drafted for ginnoir review |
| **1** | `feat/m1-foundations` | #3, #4 | Queue 3+ actions; multi-resource costs/unlocks work |
| **2** | `feat/m1-playable-loop` | #5, #6 | Stub story branch — pick A vs B, outcomes differ |
| **3** | `feat/m1-progression` | #7, #8, #11 | Full arc → prestige; second run catches up |
| **4** | `feat/m1-polish` | #9, #10, #12 | Mobile-ready; save export/import UX; balance tuned; M1 closed |

## Dependency graph

```text
Phase 0 (outline) ──────────────────────────────┐
                                                 │ gate before PR3 content
PR1 foundations ──► PR2 story+queue UI ──► PR3 progression ──► PR4 polish
     │                    │                      │
     └─ stub content      └─ stub story graph    └─ real content replaces stubs
```

PR1 must merge before PR2 (story graph assumes expanded game state + queue). PR3 requires Phase 0 approval for T3.3. PR4 assumes all gameplay systems exist.

---

## Phase 0 — Story outline (vault, parallel with PR1–2)

**Tool:** Claude Code (+ ginnoir review in chat/Cursor)

**Work:**

1. Fill `Idlegame/Story/Outline.md` §M1 arc beat skeleton: Hook → First loop → Branch (routes A/B) → Automation beat → Prestige climax.
2. Draft passage prose for each beat; ginnoir reviews/edits in vault.
3. Record any new design decisions in `Idlegame/Decisions.md`.

**Gate:** ginnoir approves the outline before PR3 branch `feat/m1-progression` merges. Does **not** block PR1 or PR2.

**Verify:** vault note has all five beats populated; ginnoir sign-off recorded in session log or Decisions.

---

## PR1 — Foundations (`feat/m1-foundations`)

**Primary tool:** Codex (GPT-5.5-Codex medium). Alt: Cursor agent (Composer 2.5).

**Gitea closes:** #3 Engine tick and offline hardening, #4 Resource and action definition set.

### T1.1 — Engine tick and offline hardening (#3)

- Expand determinism regression tests: same elapsed wall time → same tick count and game state regardless of `advance()` chunking.
- Document offline behavior: tick loop `maxTicks` batching vs save-layer `DEFAULT_MAX_OFFLINE_MS` clamp (already in `save.ts`).
- Add/extend engine purity guard: no React/DOM imports under `src/engine/` (test or lint rule if lightweight).
- Keep `tickGame` pure; queue logic lands in T1.3.

*Verify:* `pnpm test:coverage` green; engine ≥80%; determinism test passes.

### T1.2 — Content schema expansion (#4)

- Extend Zod schemas in `src/content/`: action **costs** (deduct on **start**; reject enqueue/start if unaffordable), **unlock conditions** (resource thresholds and/or story flags placeholder field for PR2), optional multi-yield. Record in `Idlegame/Decisions.md` as D-0010 if not already covered.
- Validation tests for malformed defs.

*Verify:* schema tests green; invalid content rejected at load boundary.

### T1.3 — Action queue engine

- Extend `GameState`: `actionQueue: string[]` (ordered action ids), retain `activeActionId` + `actionElapsedMs`.
- API: `enqueueAction`, `cancelQueuedAction(index)`, `clearQueue` (if scoped); on action completion, auto-start next queued action.
- `tickGame` unchanged semantics for active action; completion handler dequeues.
- Unit tests: queue ordering, cancel, auto-advance, empty queue idle.

*Verify:* queue tests green; no UI required yet.

### T1.4 — Stub content pack

- Replace walking-skeleton defs with M1-shaped placeholder set: **2 resources**, **4–5 timed actions** with costs/unlocks (generic names like "Supplies", "Scout the path").
- Keep human-readable durations (seconds-scale for dev; balance in PR4).

*Verify:* action completion + cost/unlock accrual tests green.

### PR1 integration verify

```powershell
pnpm typecheck
pnpm lint
pnpm test:coverage
pnpm build
```

Manual playtest: enqueue 3 actions → they run sequentially → resources reflect costs/yields → reload preserves queue state.

**PR:** conventional commits, link `Closes #3`, `Closes #4` in merge commit or PR body.

---

## PR2 — Playable loop (`feat/m1-playable-loop`)

**Primary tools:** Codex (T2.1–T2.2 engine), Antigravity (T2.3–T2.5 UI + browser verify).

**Gitea closes:** #5 Action queue UI, #6 Story graph and first branch.

### T2.1 — Story graph engine (#6)

- New module `src/engine/story.ts` (or `storyGraph.ts`): traverse nodes, evaluate choice requirements, apply outcomes (set flags, grant/consume resources, route to next node).
- Extend `GameState`: `storyFlags: Record<string, boolean>`, `currentStoryNodeId: string`, `seenStoryNodeIds: string[]` (for prestige catch-up in PR3).
- Emit story events for the event log (pure data — UI renders).
- Unit tests: linear traversal, branch by choice, gated node blocked until requirements met.

*Verify:* story traversal tests green; engine stays React-free.

### T2.2 — Story content schema

- Zod-validated story node defs in `src/content/`: id, prose, choices (label, requirements, outcomes, target node), auto-advance nodes optional.
- Wire into content loader alongside resources/actions.

*Verify:* schema validation tests; invalid graph (dangling node id) fails at load.

### T2.3 — Action queue UI (#5)

- Upgrade `ActionPanel`: enqueue button per unlocked action, visible queue list, cancel queued item, active action progress bar (extend M0 pattern).
- Disabled state when action locked or unaffordable.

*Verify:* browser — queue 2+ actions, cancel one, watch order respected.

### T2.4 — Story panel UI

- New component: current passage prose, choice buttons when node has choices, integrate with runtime commands.
- Event log receives story transition entries.

*Verify:* browser — story panel renders; choice click advances node.

### T2.5 — Stub story graph

- ~6 nodes, **one branching choice** (routes A/B), placeholder prose proving mechanics.
- Hook stub graph to stub actions (e.g., branch unlocks different actions).

*Verify:* browser — complete route A vs route B → different flags/resources/log entries.

### PR2 integration verify

Full pre-PR chain + desktop browser smoke. Stub prose is explicitly temporary.

**PR:** link `Closes #5`, `Closes #6`.

---

## PR3 — Progression (`feat/m1-progression`)

**Gate:** Phase 0 outline approved by ginnoir.

**Primary tools:** Claude Code (T3.3 content encode + prose fidelity), Codex (T3.1–T3.2 engine).

**Gitea closes:** #7 Automation unlock, #8 First prestige reset, #11 Opening arc content.

### T3.1 — Automation unlock (#7)

- Track per-action manual completion count in `GameState`.
- After first manual completion, action becomes **automatable** (toggle or auto-enqueue repeat — pick enqueue-repeat for M1 simplicity).
- Automation respects costs; stops if unaffordable (document behavior).
- In-fiction story beat references automation (content in T3.3).

*Verify:* tests — locked before first completion, unlocked after; automated repeats fire.

### T3.2 — First prestige reset (#8)

- Prestige trigger: story node or dedicated action at arc end.
- Reset: clear run resources, queue, active action; **retain** `prestigeLayer`, `knowledgeFlags` / `seenStoryNodeIds`, automation unlocks.
- Catch-up: known story nodes fast-forward (skip prose or abbreviated passage — implement minimal fast-forward for M1).
- `prestigeCount` increment; new prestige/story fields added to runtime + save payload in PR3 (still `SAVE_VERSION=1` until PR4); PR4 bumps version and ships v1→v2 migration.

*Verify:* tests — reset clears run state, retains knowledge; second run skips/fast-forwards seen nodes; browser full arc → prestige → new run starts faster.

### T3.3 — Opening arc content (#11)

- Replace stub resources/actions/story graph with vault-approved opening arc from `Idlegame/Story/Outline.md`.
- Encode prose into `src/content/` story defs; link vault note in PR description.
- Branch choice must **matter** (different content, not flavor-only — per GDD).

*Verify:* content schema tests; ginnoir in-app text review; vault cross-link present.

### PR3 integration verify

Full pre-PR chain. Playtest: start → branch → automation unlock → prestige → second run with catch-up. File brief playtest notes in vault.

**PR:** link `Closes #7`, `Closes #8`, `Closes #11`.

---

## PR4 — Polish & close (`feat/m1-polish`)

**Primary tools:** Codex (T4.1 save), Antigravity (T4.2 mobile), Claude Code + ginnoir (T4.3 balance).

**Gitea closes:** #9 Save migrations and import/export UX, #10 Mobile layout pass, #12 Balance pass.

### T4.1 — Save migrations and import/export UX (#9)

- Bump `SAVE_VERSION` to 2; implement v1→v2 migration (add new fields with sane defaults).
- Migration registry pattern for future versions.
- Settings UI: export save string (copy), import with validation + explicit confirm (overwrite).
- Tampered import rejected with user-visible error.

*Verify:* migration unit tests; tamper rejection; browser export → clear storage → import → state restored.

### T4.2 — Mobile layout pass (#10)

- 375px viewport: no clipping/overlap; touch targets adequate; story panel + queue usable one-handed.
- Desktop unchanged unless fixes apply globally.

*Verify:* Antigravity screenshots desktop + mobile; core flow works on mobile viewport.

### T4.3 — Balance pass (#12)

- Tune action durations, resource rates, choice cadence, time-to-first-prestige for semi-active pacing (~few-minute choice cadence target from GDD).
- Document tuning rationale in vault (`Idlegame/Decisions.md` or new `Idlegame/Balance/M1.md`).

*Verify:* timed playtest observations recorded; ginnoir sign-off on feel.

### T4.4 — Milestone close

- Update `Idlegame/_Claude.md` session log; GDD milestone map (M1 complete, M2 TBD).
- Close Gitea milestone **M1 Vertical Slice**; ensure #3–#12 closed.
- README current-scope blurb → M1 complete.

*Verify:* vault updated; Gitea milestone closed; `main` deploy green.

### PR4 integration verify

Full pre-PR chain. Final playtest on `idlegame.ginnoir.com`.

**PR:** link `Closes #9`, `Closes #10`, `Closes #12`.

---

## AI tool routing (M1)

One tool per branch at a time. Default: phase owner merges before next phase starts.

| Phase / task | Tool | Model tier | Why |
|---|---|---|---|
| Phase 0 outline + prose | Claude Code | Opus 4.8 | Story/design lane |
| PR1 T1.x | Codex | GPT-5.5-Codex medium | Scoped engine + TDD |
| PR2 T2.1–T2.2 | Codex | GPT-5.5-Codex medium | Story graph engine |
| PR2 T2.3–T2.5 | Antigravity | Gemini 3 Pro | Browser verification |
| PR3 T3.1–T3.2 | Codex | GPT-5.5-Codex highest | Prestige = state integrity surface |
| PR3 T3.3 | Claude Code | Opus 4.8 | Vault prose → content defs |
| PR4 T4.1 | Codex | GPT-5.5-Codex medium | Save migration discipline |
| PR4 T4.2 | Antigravity | Gemini 3 Pro | Mobile screenshots |
| PR4 T4.3 | Claude Code + ginnoir | Opus 4.8 / chat | Balance + playtest feel |
| Ginnoir review gates | Cursor / chat | Composer 2.5 | Phase 0 prose, balance sign-off |

Cursor is the interactive lane for scoped tweaks anytime ginnoir is driving.

## Error handling expectations

- Invalid saves, content, or import strings: **fail explicitly** at boundary with clear errors (existing M0 pattern).
- Unknown action/story node ids: throw in engine API (dev-time content errors, not player-facing soft-fail).
- Migration failure: reject load, preserve prior save if possible, surface message in UI.

## Testing expectations

- New engine behavior: unit tests required; maintain ≥80% coverage on `src/engine/`.
- UI phases: browser smoke required (Antigravity or manual); Playwright deferred post-M1.
- Each PR runs the full pre-PR verification chain before merge.

## Out of scope (M1)

- Playwright E2E suite
- Second prestige layer or new mechanics between layers
- Cloud saves / accounts
- Public playtest (internal-only Caddy remains)
- Art pipeline, battle screen, i18n
- Steam/Tauri / Capacitor wraps

## Gitea issue index

| Issue | Title | Phase |
|---|---|---|
| #3 | Engine tick and offline hardening | PR1 |
| #4 | Resource and action definition set | PR1 |
| #5 | Action queue UI | PR2 |
| #6 | Story graph and first branch | PR2 |
| #7 | Automation unlock | PR3 |
| #8 | First prestige reset | PR3 |
| #11 | Opening arc content | PR3 |
| #9 | Save migrations and import/export UX | PR4 |
| #10 | Mobile layout pass | PR4 |
| #12 | Balance pass | PR4 |

Plane epics (Vertical Slice, Game Design) link these issues by URL — no Plane task duplication required during execution.

---

*Brainstorm approved by ginnoir 2026-06-11. Next step after spec review: invoke `writing-plans` for task-level implementation plans per PR if desired, or begin Phase 0 / PR1 directly via `executing-plans`.*