Seven Tentacles

Table of Contents

• The Vision
  • The Core Insight
  • The Stack
  • Target Outcome
• The Seven Agents
• The Cephalopod Journey
• Quick Start
• Project Structure
• Documentation
• Contributing
  • Priority Areas
• License
• Acknowledgments

Teaching Compiler Architecture to Ages 8-18 Through Progressive Reveal & Playful Mascots

The Vision

Seven Tentacles is a radically innovative 10-year learning framework that teaches university and graduate-level compiler architecture concepts to children aged 8-18 without them realizing it.

The Core Insight

Kids learn by playing games with colorful mascots. At age 8, they meet "Speedy Red" and play racing games. At age 16, they discover that "Speedy Red" has been teaching them about recursive descent parsing, and Red now goes by "Performance Agent Red." They’ve been learning compilers for 8 years without noticing.

The Stack

• 7 cephalopod mascots (octopus agents) — each teaches one compiler component

• 4 language dialects (Me, Solo, Duet, Ensemble) — matching their age/maturity

• Progressive reveal system — concepts introduced as games, revealed as CS

• 10-year narrative journey — Cuttle → Squidlet → Duet → Octopus

Target Outcome

16-year-olds with graduate-level understanding of:

• Parsing & lexical analysis

• Concurrency & async/await

• Type systems & affine types

• AST construction & manipulation

• Audit trails & verification

• Compile-time evaluation

• Language governance & policy enforcement

The Seven Agents

Agent	Role	Teaches
🔴 Red	The Parser	Lexical analysis → Parsing → Syntax trees
🟠 Orange	The Concurrency Engine	Async/await, scheduling, event loops
🟡 Yellow	The Type System	Type systems, affine types, memory safety
🟢 Green	The AST Architect	Abstract syntax trees, code representation
🔵 Blue	The Auditor	Verification, auditing, tracing, debugging
🟣 Indigo	The Metaprogrammer	Compile-time evaluation, macros, reflection
🟤 Violet	The Governance System	Language design, policy enforcement, ethics

The Cephalopod Journey

🐚 Cuttle (8-12)	Baby cuttlefish. One tentacle at a time. Visual "Me Language."
🦑 Squidlet (13-14)	Adolescent squid. Names change. CS concepts emerge.
🦑🦑 Duet (15)	Two squid dancing. Explicit agent collaboration.
🐙 Octopus (16+)	Full orchestration. Build complete compilers.

Quick Start

# Clone the repository
git clone https://gitlab.com/hyperpolymath/seven-tentacles.git
cd seven-tentacles

# Enter development environment
nix develop  # or: guix shell -D -f guix.scm

# Build everything
just build

# Run the reveal demo
just demo

# Run tests
just test

Project Structure

seven-tentacles/
├── curriculum/           # All lesson content
│   ├── cuttle/          # Ages 8-12 (140+ lessons)
│   ├── squidlet/        # Ages 13-14 (210+ lessons)
│   ├── duet/            # Age 15 (70+ lessons)
│   └── octopus/         # Ages 16+ (advanced projects)
├── languages/           # Language implementations
│   ├── me-language/     # Visual Blockly-like
│   ├── solo-language/   # Text with affine types
│   ├── duet-language/   # Two-party protocols
│   └── ensemble-language/ # Full orchestration
├── agents/              # ReScript agent definitions
├── tools/               # Reveal system, lesson player
├── assets/              # Mascots, sprites, sounds
├── docs/                # Pedagogy, teacher guides
├── tests/               # Curriculum tests
└── examples/            # Playable demos

Documentation

• VISION.adoc — Complete pedagogical framework

• PEDAGOGY.adoc — Learning science research

• AGENT_INTERVIEWS.adoc — Agent personalities

• TEACHER_GUIDE.adoc — Classroom usage

Contributing

We welcome contributions! Please see our contribution guidelines.

Priority Areas

1. Curriculum content — Writing lessons for all 7 agents

2. Language implementations — Me, Solo, Duet, Ensemble

3. Mascot art — SVG illustrations for all agents

4. Accessibility — WCAG 2.1 AA compliance

5. Translations — Making it global

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Acknowledgments

Designed by Jonathan D.A. Jewell with contributions from the global CS education community.

---

"The Seven Tentacles framework combines pedagogical innovation, narrative design, and formal CS concepts into a unified system. This is not just another educational game — it’s a 10-year learning journey that secretly teaches graduate-level concepts."