interactive-story/planning/BUILD-MILESTONES.md

Adventure Storyteller — Build Milestones

Status: Placeholder / intentionally incomplete
Do not use for production implementation yet.

1. Purpose

The detailed production implementation plan will be created at the end of Phase 0 — Research, Validation & Architecture.

A precise plan cannot responsibly be written before the project has selected:

• the base repository or build strategy,
• the final persistence/story-tree design,
• the final browser architecture,
• the Ollama integration model,
• the memory/retrieval strategy,
• the local-only hardening approach,
• the migration/reuse plan for inherited code.

2. Why This Document Is Deliberately Limited

Different fork choices create fundamentally different engineering work.

Example:

If Open Dungeon is selected

Early milestones may require:

• adding immutable story-tree persistence,
• adding branch-aware state restoration,
• introducing structured narrative state,
• adding long-term semantic memory.

If AI-DnD is selected

Early milestones may instead require:

• removing RPG mechanics,
• removing cloud providers,
• removing account/hosted assumptions,
• simplifying world state while preserving story-tree behavior.

If ai-adventure is selected

Early milestones may instead require:

• adding an Ollama adapter,
• adding a browser API,
• building the browser UI,
• extending lore retrieval beyond current behavior.

A single detailed build plan written now would therefore contain false precision.

3. Expected High-Level Production Phases

These are directional only and must be rewritten after Phase 0.

Phase 1 — Production Foundation

• establish production fork/repository,
• preserve upstream provenance,
• remove or isolate unwanted functionality,
• establish development/test environment,
• confirm local Ollama integration.

Phase 2 — Authoritative Story Persistence

• immutable/recoverable turn history,
• branch parentage,
• checkpoints,
• restore,
• retry/edit semantics,
• transactional commits.

Phase 3 — Narrative State

• generic entities,
• facts,
• relationships,
• story threads,
• state extraction/validation,
• state inspector.

Phase 4 — Long-Term Memory

• summaries,
• older-turn retrieval,
• token budgeting,
• provenance,
• continuity handling.

Phase 5 — Local Knowledge Library

• local file imports,
• Canon / Reference / Inspiration classes,
• chunking,
• local indexing,
• optional local embeddings,
• retrieval inspection.

Phase 6 — Browser UX Completion

• campaign management,
• transcript,
• branching visualization,
• checkpoints,
• state/editor,
• library management,
• prompt inspection,
• responsive local UI.

Phase 7 — Local-Only Hardening

• remove remote providers,
• remove telemetry/analytics,
• remove runtime CDN dependencies,
• enforce/validate local endpoints,
• network tests,
• offline operation tests.

Phase 8 — Export, Backup, and Recovery

• campaign export,
• import,
• backups,
• migration,
• corruption/error recovery.

Phase 9 — Future-Media Hooks

• scene snapshots,
• visual character/location descriptors,
• asset schema,
• media-provider interfaces,
• no required image/video implementation.

Phase 10 — v1 Validation and Release

• regression testing,
• long-story testing,
• rollback/branch tests,
• offline test,
• migration test,
• documentation,
• release packaging.

4. Gate Before This Plan Becomes Active

Do not convert the high-level phases above into Codex implementation prompts until all of the following exist:

• SPECIFICATION.md v1.0,
• TECHNICAL-DESIGN.md v1.0,
• completed Phase 0 research reports,
• approved fork/build ADR,
• approved licensing/reuse review.

5. Required Format for the Final Build Plan

When rewritten after Phase 0, every production milestone should contain:

• objective,
• scope,
• explicit non-scope,
• prerequisite milestones,
• files/components expected to change,
• implementation tasks,
• data/schema changes,
• tests required,
• security/privacy checks,
• acceptance criteria,
• rollback/migration notes,
• documentation updates,
• definition of done.

The final document should be suitable for handing directly to Codex one milestone at a time.