= Seven Tentacles: Path to MVP v1
:toc: left
:toclevels: 3
:icons: font
:sectnums:

*Strategic Roadmap, Complexity Analysis, and Risk Assessment*

== Executive Summary

**Current State:** ~15% complete (foundation + 3 tabletop games)
**MVP v1 Target:** Playable Cuttle stage (ages 8-12) with one complete learning path
**Estimated Effort:** 12-16 weeks for solo developer, 6-8 weeks with 2-3 contributors
**Key Risk:** Curriculum content creation is the bottleneck, not technology

== What We Have Now

=== Completed (✅)

[cols="2,1,3"]
|===
|Component |Status |Notes

|Framework Design |100% |VISION.adoc, pedagogy model
|ReScript Agent Definitions |100% |All 7 agents with personalities
|RSR Compliance |100% |All required files
|Build Infrastructure |100% |flake.nix, Justfile, CI
|Reveal Demo |100% |Interactive HTML demo
|Lesson Player Template |80% |Needs curriculum integration
|Tabletop Games |43% |3 of 7 agents (Red, Yellow, Blue)
|Cuttle Curriculum |8% |11 of 140 lessons
|Me Language |5% |Examples only, no interpreter
|===

=== Summary

* **Strong:** Design, documentation, infrastructure
* **Weak:** Actual content (curriculum), working software

== MVP v1 Definition

=== Minimum Viable Product

A working system where:

1. A child aged 8-12 can complete **one full agent path** (20 lessons)
2. Lessons are playable in browser (no install)
3. Progress is saved locally
4. At least 3 agents have tabletop alternatives
5. Teacher can facilitate without technical knowledge

=== What MVP v1 Includes

[cols="1,2,1"]
|===
|Component |Scope |Priority

|Red Agent Path |20 complete lessons (Cuttle) |P0
|Me Language (Basic) |Block-based, runs in browser |P0
|Lesson Player |Plays curriculum, tracks progress |P0
|Tabletop Games |All 7 agents |P1
|Yellow Agent Path |20 complete lessons |P1
|Blue Agent Path |20 complete lessons |P1
|Web Deployment |Static hosting (GitHub Pages) |P1
|Progress System |LocalStorage, exportable |P2
|Accessibility |WCAG 2.1 AA basics |P2
|===

=== What MVP v1 Excludes

* Squidlet/Duet/Octopus stages (ages 13+)
* Solo/Duet/Ensemble languages
* User accounts / cloud sync
* Mobile apps
* Full 140-lesson Cuttle curriculum
* Formal assessment system
* Teacher dashboard
* Translations

== Work Breakdown

=== 1. Curriculum Content (THE BIG ONE)

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Red Lessons 6-20 |Complete racing/parsing curriculum |15 lessons × 2hr |Low
|Yellow Lessons 2-20 |Complete sorting/types curriculum |19 lessons × 2hr |Low
|Blue Lessons 2-20 |Complete mystery/verification curriculum |19 lessons × 2hr |Low
|Orange Lessons 1-20 |Juggling/concurrency curriculum |20 lessons × 2hr |Medium
|Green Lessons 1-20 |Building/AST curriculum |20 lessons × 2hr |Medium
|Indigo Lessons 1-20 |Magic/metaprogramming curriculum |20 lessons × 2hr |Medium
|Violet Lessons 1-20 |Rules/governance curriculum |20 lessons × 2hr |Low
|===

**Total curriculum effort:** ~260 hours (6-7 weeks full-time)

**Why it's the bottleneck:**
* Each lesson needs careful pedagogical design
* Hidden concepts must map correctly to CS
* Activities need to be genuinely fun
* Cannot be easily automated or outsourced

=== 2. Tabletop Games (Remaining 4)

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Orange Tabletop |Timing/juggling card game |4hr rules + 4hr cards |Medium
|Green Tabletop |Building/construction game |4hr rules + 4hr cards |Medium
|Indigo Tabletop |Spell/transformation cards |4hr rules + 4hr cards |Medium
|Violet Tabletop |Rule-making/voting game |4hr rules + 4hr cards |Low
|===

**Total tabletop effort:** ~32 hours

=== 3. Me Language Implementation

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Blockly Integration |Set up Blockly with custom blocks |8hr |Medium
|Agent Blocks |Create blocks for each agent |12hr |Low
|Simple Interpreter |Execute block programs |16hr |High
|Visual Output |Show results, animations |12hr |Medium
|Error Messages |Agent-personality errors |8hr |Low
|Curriculum Integration |Connect to lessons |8hr |Medium
|===

**Total Me Language effort:** ~64 hours

=== 4. Lesson Player (Production)

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Curriculum Loader |Parse AsciiDoc lessons |8hr |Medium
|Activity Renderer |Render games, quizzes, etc |16hr |High
|Progress Tracking |LocalStorage persistence |4hr |Low
|Agent Personality |Voice, reactions, messages |8hr |Low
|Navigation |Lesson flow, prerequisites |4hr |Low
|Mobile Responsive |Works on tablets |8hr |Medium
|===

**Total lesson player effort:** ~48 hours

=== 5. Web Deployment

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Static Build |Bundle for deployment |4hr |Low
|GitHub Pages |Deploy static site |2hr |Low
|Domain Setup |Custom domain (optional) |1hr |Low
|CI/CD |Auto-deploy on push |4hr |Medium
|===

**Total deployment effort:** ~11 hours

=== 6. Accessibility (Basic)

[cols="1,2,1,1"]
|===
|Task |Description |Effort |Complexity

|Keyboard Navigation |All interactions keyboard-accessible |8hr |Medium
|Screen Reader |ARIA labels, semantic HTML |8hr |Medium
|Color Contrast |WCAG AA compliance |4hr |Low
|Focus Indicators |Visible focus states |2hr |Low
|===

**Total accessibility effort:** ~22 hours

== Total Effort Summary

[cols="1,1,1"]
|===
|Category |Hours |Weeks (40hr)

|Curriculum Content |260 |6.5
|Tabletop Games |32 |0.8
|Me Language |64 |1.6
|Lesson Player |48 |1.2
|Deployment |11 |0.3
|Accessibility |22 |0.5
|Testing & Polish |40 |1.0
|**TOTAL** |**477** |**~12 weeks**
|===

**With parallelization:** 8-10 weeks (content + tech in parallel)
**With contributors:** 6-8 weeks (2-3 people)

== Roadmap

=== Phase 1: Foundation Complete (Weeks 1-2)

* [x] Framework design
* [x] Agent definitions
* [x] RSR compliance
* [x] 3 tabletop games
* [ ] Remaining 4 tabletop games
* [ ] Basic CI/CD

**Deliverable:** All 7 tabletop games playable

=== Phase 2: Red Path Complete (Weeks 3-5)

* [ ] Red lessons 6-20 written
* [ ] Me Language basic implementation
* [ ] Lesson player with Red content
* [ ] Progress tracking

**Deliverable:** Complete Red agent path playable in browser

=== Phase 3: Expand Content (Weeks 6-9)

* [ ] Yellow lessons 2-20
* [ ] Blue lessons 2-20
* [ ] Orange lessons 1-10
* [ ] Activity types expanded
* [ ] Accessibility pass

**Deliverable:** 3 complete paths, 60+ lessons

=== Phase 4: MVP Polish (Weeks 10-12)

* [ ] Green lessons 1-10
* [ ] Indigo lessons 1-10
* [ ] Violet lessons 1-10
* [ ] Full accessibility audit
* [ ] Performance optimization
* [ ] User testing (if possible)
* [ ] Documentation for teachers

**Deliverable:** MVP v1 launch-ready

=== Post-MVP Roadmap

[cols="1,2,2"]
|===
|Version |Focus |Timeline

|v1.1 |Complete all 140 Cuttle lessons |+4 weeks
|v1.2 |Teacher dashboard, class management |+4 weeks
|v2.0 |Squidlet stage (ages 13-14), Solo Language |+12 weeks
|v2.5 |Duet stage (age 15), protocols |+8 weeks
|v3.0 |Octopus stage (16+), full compiler project |+16 weeks
|===

== Complexity Analysis

=== Low Complexity (Do First)

* Curriculum writing (tedious but straightforward)
* Tabletop game design (we have the pattern)
* Static deployment
* Basic progress tracking

=== Medium Complexity (Plan Carefully)

* Blockly integration (well-documented but fiddly)
* Activity renderers (many edge cases)
* Accessibility (ongoing effort)
* Mobile responsiveness

=== High Complexity (Prototype First)

* Me Language interpreter (need clear semantics)
* Interactive game activities (each is unique)
* Curriculum-to-player pipeline (format decisions)

=== Unknown Complexity (Research Needed)

* User testing with actual children
* Pedagogical validation
* Long-term engagement patterns

== Ambiguities & Open Questions

=== Curriculum Format

**Question:** What format for lesson files?

**Options:**
1. AsciiDoc (current) - human-readable, needs parser
2. JSON/YAML - machine-readable, less pleasant to write
3. MDX - React-friendly, more tooling
4. Custom DSL - maximum flexibility, maintenance burden

**Recommendation:** Keep AsciiDoc for authoring, build a parser that extracts structured data. Or use YAML frontmatter + AsciiDoc body.

=== Activity Implementation

**Question:** How do we implement diverse activities (games, quizzes, puzzles)?

**Options:**
1. Each activity type is a React/Svelte component
2. Generic activity engine with configuration
3. Embed external game engines (Phaser, etc.)
4. Simple HTML/CSS/JS per activity

**Recommendation:** Start with simple HTML/JS activities, extract patterns, then build generic engine.

=== Progress & Assessment

**Question:** How do we know if learning is happening?

**Options:**
1. Completion tracking only (did they finish?)
2. Quiz scores (did they answer correctly?)
3. Time-on-task (are they engaged?)
4. Skill mastery (can they apply concepts?)

**Recommendation:** Start with completion + quiz scores. Design for skill mastery later.

=== Reveal Timing

**Question:** When exactly do concepts get revealed?

**Current design:** Age-based (8-12 Cuttle, 13-14 Squidlet, etc.)

**Problem:** Kids don't age in sync with curriculum progress. A fast 10-year-old might be ready for reveals before a slow 14-year-old.

**Options:**
1. Strict age gates (current)
2. Progress-based reveals (complete X lessons)
3. Teacher-controlled reveals
4. Learner-chosen reveals

**Recommendation:** Progress-based with age as a guideline, teacher override.

=== Multiplayer / Social

**Question:** Should kids be able to play together?

**MVP answer:** No, solo experience only.

**Future consideration:** Cooperative challenges could reinforce learning. Duet stage naturally suggests pairs.

== Challenges

=== Content Quality at Scale

**Challenge:** Writing 400+ lessons while maintaining pedagogical quality.

**Mitigation:**
* Template-driven lesson structure
* Clear guidelines for contributors
* Review process before merge
* Iterative improvement based on feedback

=== Testing with Children

**Challenge:** Need actual children to validate learning outcomes.

**Mitigation:**
* Partner with schools/teachers for pilots
* Start with own children/family of contributors
* Use teacher feedback as proxy
* Design for easy A/B testing later

=== Long-term Maintenance

**Challenge:** 10-year framework needs 10+ years of maintenance.

**Mitigation:**
* Open source community
* Simple, maintainable tech stack
* Documentation for future contributors
* Avoid trendy frameworks that may die

=== Funding & Sustainability

**Challenge:** Educational projects often struggle for funding.

**Options:**
* Grants (educational foundations)
* Donations (GitHub Sponsors, Open Collective)
* Commercial licensing for schools
* OpenLearn partnership
* Book/merchandise

=== Scope Creep

**Challenge:** Framework is ambitious; easy to keep adding features.

**Mitigation:**
* Strict MVP definition
* "Not in v1" list (enforced)
* Regular scope reviews
* Ship early, iterate

== Opportunities

=== OpenLearn Partnership

**Opportunity:** Open University's free learning platform.

**Value:**
* Credibility and reach
* Pedagogical expertise
* Existing learner base
* Potential research collaboration

**Action:** Complete MVP, then approach with working demo.

=== Research Publications

**Opportunity:** Novel pedagogy = publishable research.

**Potential papers:**
1. "Progressive Reveal in CS Education" (SIGCSE)
2. "Teaching Compilers to Children" (ITiCSE)
3. "Game-Based Type System Education" (CHI)
4. "10-Year Learning Journeys" (longitudinal study)

**Action:** Document methodology now, collect data from start.

=== Teacher Community

**Opportunity:** Teachers sharing resources, lessons, adaptations.

**Value:**
* Curriculum contributions
* Real-world testing
* Word-of-mouth growth
* Sustainability

**Action:** Build community infrastructure early (forum, Discord, etc.)

=== International Expansion

**Opportunity:** Translate to other languages.

**Considerations:**
* Agent names may need cultural adaptation
* Some games may not translate well
* Right-to-left language support
* Localization of code examples

**Action:** Design for i18n from start, even if not implementing yet.

=== Corporate Training

**Opportunity:** Adults learning compilers could use this too.

**Consideration:** Would need "adult mode" without cutesy mascots, but same progressive reveal could work.

**Action:** Not MVP, but keep architecture flexible.

== Risk Register

[cols="2,1,1,2"]
|===
|Risk |Likelihood |Impact |Mitigation

|Curriculum takes longer than estimated |High |High |Start with 1 complete path, expand
|Children don't find it fun |Medium |Critical |Test early, iterate, involve kids in design
|Blockly integration issues |Medium |Medium |Prototype early, have fallback plan
|No contributors join |Medium |Medium |Build MVP solo, community comes after launch
|Similar project emerges |Low |Medium |Focus on unique progressive reveal angle
|Funding runs out |Medium |High |Keep costs low, pursue grants early
|===

== Recommended Next Steps

=== Immediate (This Week)

1. **Complete tabletop games** - Finish Orange, Green, Indigo, Violet
2. **Define curriculum format** - Decide on AsciiDoc + YAML frontmatter or alternative
3. **Prototype Me Language** - Get Blockly rendering one simple program

=== Short-term (Next 2 Weeks)

1. **Write Red lessons 6-20** - Complete first full path
2. **Build lesson loader** - Parse curriculum files
3. **Deploy preview** - GitHub Pages with what exists

=== Medium-term (Next Month)

1. **Complete 3 agent paths** - Red, Yellow, Blue fully playable
2. **Basic progress tracking** - LocalStorage implementation
3. **First user testing** - Even informal feedback helps

== Questions for You

Before proceeding, it would help to clarify:

1. **Timeline pressure:** Is there a deadline (grant, school year, etc.)?

2. **Resource availability:** Solo effort or potential contributors?

3. **Target audience priority:** Schools? Homeschool? Self-directed learners?

4. **Technical preferences:** Any strong opinions on React vs Svelte vs vanilla JS?

5. **Content creation:** Will you write curriculum, or need contributor process?

6. **Tabletop vs Digital:** Equal priority, or one first?

---

*Document Version:* 1.0
*Last Updated:* December 2025
*Status:* Planning
