interactive-story/planning/RESEARCH-PLAN.md

Adventure Storyteller — Phase 0 Research Plan

Status: Ready for execution
Phase: 0 — Research, Validation & Architecture
Goal: Determine what to build, what to fork/reuse, and finalize the technical design before production implementation begins.

1. Why Phase 0 Exists

The project has several promising open-source starting points. They differ substantially in:

• browser UX,
• persistence model,
• branching semantics,
• long-term memory,
• local knowledge retrieval,
• Ollama support,
• dependency footprint,
• privacy/network behavior,
• game-specific assumptions,
• licensing,
• test quality.

A detailed production milestone plan written before inspecting the code would rely on guesses.

Phase 0 therefore ends when we can answer:

What exact codebase and architecture should be used for the production storyteller?

No production feature work should begin before that decision unless explicitly authorized.

2. Candidate Repositories

Initial candidates:

1. Open Dungeon

   • Repository: newideas99/open-dungeon
   • Interest: browser-first interactive-fiction UX, Ollama, SQLite.

2. AI-DnD

   • Repository: parththakkar106/AI-DnD
   • Interest: browser UI, story tree, rollback, memory, story cards, prompt inspection.

3. Local Adventure Engine / ai-adventure

   • Repository: CaoRuiming/ai-adventure
   • Interest: append-only state, checkpoints, branching, privacy-focused architecture, deterministic replay.

4. aiMultiFool

   • Repository: exact upstream URL to be confirmed during inventory.
   • Interest: local semantic memory/RAG and context inspection.

Reference projects:

• SillyTavern
• RisuAI
• KoboldAI
• Chronicler
• other credible projects discovered during Phase 0.

3. Research Workspace

Create a dedicated workspace such as:

adventure-storyteller-research/
├── candidates/
│   ├── open-dungeon/
│   ├── ai-dnd/
│   ├── ai-adventure/
│   └── aimultifool/
├── notes/
├── experiments/
├── reports/
└── inventory/

Do not copy source code from one project into another during initial analysis.

Each candidate should remain a clean upstream clone or worktree.

Record:

• upstream URL,
• upstream default branch,
• commit SHA examined,
• release/tag if applicable,
• clone date,
• license,
• language/framework,
• build tooling,
• runtime services,
• expected local ports.

4. Phase Rules

During Phase 0:

• do not begin production feature development,
• do not merge candidate codebases,
• do not remove features from candidate repos,
• do not commit speculative refactors,
• small disposable experiments are allowed,
• experiments must be isolated and clearly documented,
• candidate repos should remain easy to reset to upstream,
• every conclusion should cite observed code/config/test behavior.

5. Milestone R0 — Research Workspace and Inventory

Objective

Create the research environment and establish a reproducible inventory of all candidates.

Tasks

• create the research workspace,
• clone all initial candidates,
• record exact upstream commits,
• locate and record licenses,
• inventory languages/frameworks,
• inventory package managers,
• inventory database/storage dependencies,
• inventory model/provider dependencies,
• inventory frontend/backend separation,
• record build/run instructions,
• identify existing tests,
• identify documentation directories,
• identify migrations/schema definitions,
• identify obvious telemetry/cloud integrations.

Deliverables

• inventory/candidates.md
• inventory/licenses.md
• inventory/dependencies.md
• inventory/build-instructions.md
• machine-readable candidate metadata if useful.

Exit Criteria

All serious candidates are locally available and reproducibly identified.

6. Milestone R1 — Build and Run Candidates

Objective

Verify actual behavior rather than relying on README claims.

Tasks

For each serious candidate:

• install dependencies,
• build successfully where applicable,
• start locally,
• create a minimal story,
• confirm persistence after restart,
• test Ollama directly where supported,
• identify how model configuration works,
• record application ports,
• identify data locations,
• inspect browser developer/network activity for unexpected outbound requests where applicable,
• record startup failures or undocumented requirements.

For projects not supporting Ollama:

• determine adapter/interface boundary,
• do not yet permanently modify the project.

Deliverables

Per candidate:

reports/runtime-<candidate>.md

Include:

• exact commands,
• success/failure,
• screenshots only if useful,
• local services used,
• observed storage files,
• observed network activity,
• known blockers.

Exit Criteria

Each serious candidate has either been run successfully or has a documented reason it cannot reasonably be evaluated.

7. Milestone R2 — Source Architecture Review

Objective

Understand how each candidate actually works internally.

Review Areas

Browser/UI

• framework,
• state management,
• streaming,
• transcript representation,
• campaign navigation,
• edit/retry behavior,
• extensibility for future media.

Backend/service layer

• routing/API design,
• model invocation boundary,
• background jobs,
• validation boundaries.

Persistence

• database type,
• schema,
• migrations,
• turn representation,
• snapshots,
• event log,
• transactions,
• branch representation.

Story history

• linear vs tree,
• retry semantics,
• undo semantics,
• destructive vs non-destructive restore,
• branch naming/navigation.

Context

• prompt assembly,
• recent history,
• summaries,
• token budgeting,
• author notes/system rules.

Memory

• summaries,
• vector retrieval,
• keyword retrieval,
• entity state,
• old-turn retrieval.

Lore/knowledge

• import formats,
• chunking,
• story cards/world info,
• semantic retrieval,
• provenance.

Tests

• unit tests,
• integration tests,
• migration tests,
• model mocks,
• coverage of state/rollback.

Deliverables

• reports/architecture-open-dungeon.md
• reports/architecture-ai-dnd.md
• reports/architecture-ai-adventure.md
• reports/architecture-aimultifool.md
• reports/architecture-comparison.md

Exit Criteria

We can explain each candidate's architecture without relying on marketing descriptions.

8. Milestone R3 — Privacy and Network Review

Objective

Determine what must be removed, disabled, or isolated to satisfy the local-only requirement.

Search For

• OpenAI,
• OpenRouter,
• Groq,
• Anthropic,
• Google,
• cloud inference,
• telemetry,
• analytics,
• Sentry,
• PostHog,
• crash reporting,
• CDN,
• Google Fonts,
• remote image hosts,
• automatic update checks,
• remote database support,
• URL retrieval,
• external web search,
• MCP,
• plugins,
• arbitrary executable scripts,
• third-party auth.

Tasks

• static source search,
• dependency review,
• environment-variable review,
• runtime network observation,
• identify outbound requests required vs optional,
• identify localhost vs wildcard binds,
• identify stored secrets/API keys,
• identify browser-side remote resources.

Deliverables

• reports/privacy-network-review.md
• per-candidate removal/mitigation list.

Exit Criteria

For each candidate, we can state exactly what local-only hardening would be required.

9. Milestone R4 — Feature and Reuse Matrix

Objective

Compare candidates by subsystem rather than declaring one project the winner prematurely.

Compare

• browser UX,
• Ollama adapter,
• streaming,
• SQLite schema,
• story tree,
• rollback,
• checkpoints,
• edit/retry semantics,
• state extraction,
• entity/world state,
• summaries,
• semantic memory,
• lexical memory,
• lore/story cards,
• source imports,
• prompt inspection,
• export/import,
• tests,
• local-only posture,
• media extensibility.

Rate Each Feature

Use categories such as:

• Keep as-is
• Keep with modification
• Reuse concept only
• Replace
• Not present
• Not wanted

Deliverables

• reports/reuse-matrix.md

Exit Criteria

We know which candidate has the best implementation of each required subsystem.

10. Milestone R5 — Licensing and Code-Reuse Review

Objective

Determine what code can legally be copied, modified, linked, or used only as inspiration.

Tasks

• verify repository licenses at the exact commits reviewed,
• note third-party code with separate licenses,
• note generated/vendor code,
• compare compatibility if combining code from multiple projects,
• pay special attention to GPL/copyleft candidates,
• distinguish:
  • direct code reuse,
  • dependency use,
  • architecture inspiration,
  • protocol/API reimplementation.

Deliverables

• reports/licensing-reuse.md

Exit Criteria

The recommended architecture does not rely on legally ambiguous code mixing.

11. Milestone R6 — Critical Prototypes

Objective

Test only the uncertainties that could change the architecture decision.

Possible experiments include:

Experiment A — Ollama adapter for ai-adventure

Determine how difficult it is to replace/extend the LM Studio adapter with Ollama.

Experiment B — Branch-safe state in Open Dungeon

Determine whether Open Dungeon's current persistence can support immutable branch parentage without invasive rewrite.

Experiment C — Strip-down feasibility in AI-DnD

Identify whether RPG/cloud systems are modular enough to remove without destabilizing core story-tree/memory behavior.

Experiment D — Local semantic retrieval

Test a minimal local embedding pipeline using Ollama and a local-only store.

Experiment E — Scene extraction

Verify that the narrator/state pipeline can produce a neutral scene packet suitable for future media.

Only run experiments that resolve a documented decision.

Deliverables

Each experiment:

experiments/<name>/README.md

Record:

• question,
• hypothesis,
• minimal changes,
• result,
• implications,
• whether code should be discarded.

Exit Criteria

No high-impact fork/architecture decision remains based solely on speculation.

12. Milestone R7 — Fork / Build Decision

Objective

Select the production starting strategy.

Required Options to Evaluate

• fork Open Dungeon,
• fork AI-DnD,
• fork/use ai-adventure core,
• clean new shell with reused permissive components,
• other candidate if discovered.

Decision Criteria

Weight heavily:

1. fit with interactive-story product,
2. browser-first architecture,
3. Ollama fit,
4. state/branch correctness,
5. local-only hardening effort,
6. amount of code to remove,
7. maintainability,
8. licensing,
9. test quality,
10. future media extensibility.

Deliverables

• reports/fork-build-recommendation.md
• ADR documenting the selected strategy.

Exit Criteria

One strategy is approved as the production base.

13. Milestone R8 — Finalize Specification and Technical Design

Objective

Convert assumptions into committed decisions.

Tasks

Update:

• SPECIFICATION.md
• TECHNICAL-DESIGN.md

Resolve:

• base repository,
• frontend framework,
• backend framework,
• storage model,
• branch/state model,
• model adapter,
• memory/retrieval strategy,
• local knowledge design,
• import formats for v1,
• context budgeting strategy,
• security boundaries,
• export format,
• future media interfaces,
• test strategy.

Mark documents v1.0 when approved.

Deliverables

• SPECIFICATION.md v1.0
• TECHNICAL-DESIGN.md v1.0
• relevant ADRs.

Exit Criteria

A developer can explain the final architecture without unresolved foundational choices.

14. Milestone R9 — Create Production Build Plan

Objective

Write the detailed implementation milestone plan only after the technical design is stable.

Tasks

Create:

• BUILD-MILESTONES.md

It must include:

• milestone dependencies,
• exact intended outcomes,
• acceptance criteria,
• test expectations,
• migration steps from selected upstream,
• removal/hardening work,
• v1 feature sequence,
• definition of done.

Exit Criteria

The build plan is specific enough to hand directly to Codex milestone-by-milestone.

15. Phase 0 Final Deliverables

At Phase 0 completion:

SPECIFICATION.md             v1.0
TECHNICAL-DESIGN.md          v1.0
RESEARCH-PLAN.md             completed
BUILD-MILESTONES.md          production-ready
DECISIONS/                   finalized foundational ADRs
reports/                     research evidence
experiments/                 critical prototype evidence
inventory/                   candidate metadata

16. Phase 0 Definition of Done

Phase 0 is complete only when:

• candidate repositories have been cloned and reviewed,
• serious candidates have been run or ruled out with evidence,
• network/privacy behavior is documented,
• licensing is understood,
• critical architectural uncertainties have been tested,
• a fork/build strategy has been selected,
• the specification is v1.0,
• the technical design is v1.0,
• the actual implementation milestone plan has been written.

At that point, production implementation can begin.