156 lines
5.5 KiB
Markdown
156 lines
5.5 KiB
Markdown
# Adventure Storyteller Planning Package
|
|
|
|
This package contains the current product requirements, provisional architecture, Phase 0 research, detailed subsystem designs, acceptance tests, and the Codex Phase 0B validation handoff for the local-only interactive-story project.
|
|
|
|
## Current Status
|
|
|
|
Phase 0A static research is complete.
|
|
|
|
The project is now ready for **Phase 0B local validation** of the three finalists:
|
|
|
|
1. AI-DnD
|
|
2. Open Dungeon
|
|
3. ai-adventure
|
|
|
|
**Do not begin production implementation yet.**
|
|
|
|
The purpose of Phase 0B is to validate the fork/base decision and resolve the remaining architecture questions with real builds, tests, offline runs, and tightly scoped experiments.
|
|
|
|
## Document Authority
|
|
|
|
Use the documents in this order when requirements appear to conflict:
|
|
|
|
1. `SPECIFICATION.md` — product requirements and desired behavior.
|
|
2. Detailed design/behavior documents listed below — elaborations of the specification.
|
|
3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail interpretation of v1 requirements.
|
|
4. `TECHNICAL-DESIGN.md` — provisional implementation direction, subject to Phase 0B findings.
|
|
5. Phase 0A reports — research evidence and candidate analysis.
|
|
6. `BUILD-MILESTONES.md` — intentionally incomplete until the fork/architecture decision is made.
|
|
|
|
The detailed design documents describe target behavior; they do not force a particular repository schema when an equivalent implementation satisfies the behavior.
|
|
|
|
## Recommended Reading Order for Codex
|
|
|
|
### A. Product and architectural intent
|
|
|
|
1. `SPECIFICATION.md`
|
|
2. `DATA-MODEL.md`
|
|
3. `STORY-BRANCH-SEMANTICS.md`
|
|
4. `CONTEXT-AND-MEMORY.md`
|
|
5. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
|
6. `SECURITY-THREAT-MODEL.md`
|
|
7. `MEDIA-EXTENSION-CONTRACT.md`
|
|
8. `BROWSER-UX-SPEC.md`
|
|
|
|
### B. Test contract
|
|
|
|
9. `TEST-CAMPAIGN-FIXTURE.md`
|
|
10. `V1-ACCEPTANCE-TESTS.md`
|
|
|
|
### C. Provisional architecture and research
|
|
|
|
11. `TECHNICAL-DESIGN.md`
|
|
12. `RESEARCH-PLAN.md`
|
|
13. `reports/PHASE-0A-STATUS.md`
|
|
14. `reports/PRELIMINARY-RECOMMENDATION.md`
|
|
15. `reports/REUSE-MATRIX.md`
|
|
16. Candidate-specific reports in `reports/`
|
|
|
|
### D. Execute
|
|
|
|
17. `PHASE-0B-CODEX-HANDOFF.md`
|
|
|
|
## Core Product Decisions Already Settled
|
|
|
|
The Phase 0B investigation should treat these as requirements rather than questions:
|
|
|
|
- browser-first UI,
|
|
- local-only v1 runtime,
|
|
- local Ollama inference,
|
|
- application-owned authoritative story state,
|
|
- complete retained transcript,
|
|
- simple user-facing Undo/Redo/Retry/Save Point semantics,
|
|
- non-destructive internal lineage,
|
|
- abandoned history retained but marked disposable; cleanup later,
|
|
- at least five Undo operations; unlimited preferred if technically straightforward,
|
|
- Redo and Retry supported,
|
|
- named checkpoints retained until explicitly deleted,
|
|
- genre-agnostic core schema,
|
|
- imported knowledge classes: Canon / Reference / Inspiration,
|
|
- local retrieval and embeddings,
|
|
- prompt/context provenance and inspection,
|
|
- no cloud inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
|
|
- future local image/video/TTS/STT capability must remain possible without coupling it to the core story engine.
|
|
|
|
## Detailed Documents
|
|
|
|
- `DATA-MODEL.md` — conceptual target data model and authority/state structures.
|
|
- `STORY-BRANCH-SEMANTICS.md` — exact Undo, Redo, Retry, Edit, checkpoint, restore, and disposable-history behavior.
|
|
- `CONTEXT-AND-MEMORY.md` — context construction, authority hierarchy, summaries, memory, retrieval, provenance, token budgeting.
|
|
- `IMPORTED-KNOWLEDGE-DESIGN.md` — import, classification, chunking, local indexing, retrieval, provenance, isolation, and prompt-injection handling.
|
|
- `SECURITY-THREAT-MODEL.md` — local trust boundary, network policy, untrusted input handling, browser security, and offline acceptance.
|
|
- `MEDIA-EXTENSION-CONTRACT.md` — future image, video, audio, TTS, and STT extension boundaries. Media remains optional and derived from story state.
|
|
- `BROWSER-UX-SPEC.md` — user-facing browser workflow and advanced inspection surfaces.
|
|
- `TEST-CAMPAIGN-FIXTURE.md` — deterministic campaign fixture for comparing candidates and later regression testing.
|
|
- `V1-ACCEPTANCE-TESTS.md` — black-box requirements and release gate.
|
|
|
|
## Phase 0A Research
|
|
|
|
Static repository research was completed on 2026-09-01.
|
|
|
|
Key reports:
|
|
|
|
- `reports/PHASE-0A-STATUS.md`
|
|
- `reports/PRELIMINARY-RECOMMENDATION.md`
|
|
- `reports/REUSE-MATRIX.md`
|
|
- `reports/AI-DND-ANALYSIS.md`
|
|
- `reports/OPEN-DUNGEON-ANALYSIS.md`
|
|
- `reports/AI-ADVENTURE-ANALYSIS.md`
|
|
- `reports/PRIVACY-STATIC-ANALYSIS.md`
|
|
- `reports/LICENSING-REUSE.md`
|
|
- `reports/SOURCE-INDEX.md`
|
|
|
|
Current preliminary architecture hypothesis:
|
|
|
|
```text
|
|
AI-DnD production base
|
|
+ ai-adventure trust/commit/privacy rules
|
|
+ Open Dungeon scene/media UX patterns
|
|
+ Chronicler memory authority tiers
|
|
+ Interactive Fiction Framework Story Bible authority/validation
|
|
+ Gamentic media-provider abstraction
|
|
```
|
|
|
|
This is a hypothesis to test, not a fork decision.
|
|
|
|
## Overall Workflow
|
|
|
|
```text
|
|
Specification + detailed behavioral designs
|
|
|
|
|
v
|
|
Phase 0A static research
|
|
|
|
|
v
|
|
Phase 0B local validation
|
|
|
|
|
v
|
|
Fork / architecture decision
|
|
|
|
|
v
|
|
SPECIFICATION v1.0
|
|
TECHNICAL-DESIGN v1.0
|
|
|
|
|
v
|
|
Detailed BUILD-MILESTONES.md
|
|
|
|
|
v
|
|
Production implementation
|
|
```
|
|
|
|
## Important Stop Rule
|
|
|
|
Phase 0B ends with evidence and a recommendation.
|
|
|
|
Codex should **not** begin production coding, repo conversion, or broad feature implementation until the Phase 0B results have been reviewed and the production base has been selected.
|