Prototype Blueprint — 30 Nodes, 7 Phases
Status: ACTIVE (structural blueprint) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-11T20:20:00Z Claim: synthesis | 2026-05-11T20:15:00Z Session: Prototype scoping — 30-node graph with 7 categorical phase lanes
Prior Context
- [[langgraph-game-surface]] — Architecture concept
- [[langgraph-unit-node-interaction-model]] — Unit/state/node model
- [[langgraph-node-anatomy]] — Node anatomy catalog
- Target: RG40XXV client, Pi/LangGraph backend, Forgejo issue backing
Shape of the Prototype
What We're Building
A 30-node LangGraph graph where: - Nodes are work items (individual tasks, not phase containers) - 7 phases are categories that nodes belong to, not the nodes themselves - Each node is backed by a Forgejo issue in a dedicated repo - A unit traverses the graph, doing work at each node - State carries config, access lists, output pointers, and traversal history - The RG40XXV renders the graph and handles input - LangGraph on Pi is the state authority
Structural Pieces (Not Yet Named)
| # | Piece | What It Is | Format |
|---|---|---|---|
| 1 | Phase definitions | 7 category lanes. Node buckets. | State dict: {"id": "planning", "name": "Planning", "order": 0} |
| 2 | Node definitions | 30 individual work items, each assigned to a phase | State dict: {"id": "node_01", "phase": "planning", "name": "...", "status": "open"} |
| 3 | Edge definitions | Valid transitions between nodes (within and across phases) | State dict: {"from": "node_01", "to": "node_02"} |
| 4 | State schema | Top-level keys, reducers, input/output schemas | Python TypedDict |
| 5 | Node functions | 30 functions — one per node. Stub implementations for prototype | Python functions |
| 6 | Unit definition | Single unit traversing the graph: role, config, access lists | State entry |
| 7 | Access gating | Per-node context access and block lists | Lists in state |
| 8 | Output locales | Per-node pointers to Forgejo issues / wiki pages | State dict |
| 9 | Turn cycle | Planning → Decision → Execution → Resolution → End-of-Turn gate | LangGraph edges + super-steps |
| 10 | Interrupt surface | Per-node pause for human input (move, accept intel, change config) | interrupt() calls |
| 11 | Forgejo repo | 30 issues, one per node + 7 phase labels + 1 project board | Forgejo on Pi (port 3001) |
| 12 | Wiki depot | Per-phase documentation pages, intel storage, harvest output | LLM wiki on Pi |
| 13 | Rendering layer | Visual representation of 30 nodes across 7 phase lanes on 640×480 | Wargame Engine + pygame |
| 14 | HTTP bridge | RG client fetches state from Pi, fires invoke on input | FastAPI or Flask on Pi |
| 15 | Checkpointer | LangGraph state persistence across invocations | SqliteSaver or MemorySaver |
Phase-to-Node Distribution (Conceptual)
30 nodes distributed across 7 phases. Distribution not yet determined — this is the variable to explore:
Planning [node_01] [node_02] [node_03] [node_04]
Research [node_05] [node_06] [node_07] [node_08] [node_09]
Define [node_10] [node_11] [node_12] [node_13]
Design [node_14] [node_15] [node_16] [node_17] [node_18]
Develop [node_19] [node_20] [node_21] [node_22] [node_23]
Deliver [node_24] [node_25] [node_26]
Review [node_27] [node_28] [node_29] [node_30]
Graph Topology (Conceptual)
Nodes within a phase form a sub-pipeline. Cross-phase edges allow skipping or revisiting:
Planning → Research → Define → Design → Develop → Deliver → Review
↑ ↑ ↑ ↑ ↑ ↑ ↑
└──────────────┴──────────────┴────────────┴────────────┴─────────────┴────────────┘
(revisit allowed — conditional edges)
Forgejo Mapping
| Graph Element | Forgejo Equivalent |
|---|---|
| Phase | Label (e.g., phase:planning) |
| Node | Issue (one per node, 30 issues) |
| Node status | Issue state (open, in_progress, done) |
| Unit at node | Assignee on issue |
| Output locale | Issue body or linked PR/wiki page |
| Access reference | Linked issue mention in body |
| Intel flag | Comment on issue with suggestion |
| Turn completion | Issue comment with checkpoint summary |
Rendering Layout (640×480 RG40XXV)
7 horizontal lanes (one per phase), nodes placed within each lane. Lanes scroll vertically or compact to fit:
┌──────────────────────────────────────────────────────────┐
│ PLANNING [01] [02] [03] [04] │
│ RESEARCH [05] [06] [07] [08] [09] │
│ DEFINE [10] [11] [12] [13] │
│ DESIGN [14] [15] [16] [17] [18] │
│ DEVELOP [19] [20] [21] [22] [23] │
│ DELIVER [24] [25] [26] │
│ REVIEW [27] [28] [29] [30] │
│──────────────────────────────────────────────────────────│
│ UNIT: Rif | NODE: node_14 | PHASE: Design │
│ [Move to...] [View output] [Accept intel] [Config] │
└──────────────────────────────────────────────────────────┘
Each node is a small rectangle or hex. Selected node highlights. Active unit shows its position. Bottom bar shows unit state and actions.
What's NOT in Scope for This Prototype
- Health, enemies, combat mechanics (pinned per earlier discussion)
- Multiple simultaneous units (single unit first, Send fan-out later)
- Intel harvesters running in background (passive harvesting deferred)
- Per-node model/harness switching (single harness for prototype)
- Auto-run mode (interactive/control mode only)
- PS2/Wii clients (RG40XXV only)
- Per-node config overrides (unit uses one config across all nodes)
What IS in Scope
- 30 nodes defined in LangGraph state, backed by 30 Forgejo issues
- 7 phase categories as organizational lanes
- One unit traversing the graph, moving between nodes via invoke()
- Per-node output locale (pointer to Forgejo issue)
- Basic access gating: unit sees only nodes in its access list
- interrupt() at each node for human decision
- RG40XXV renders graph via Wargame Engine/pygame
- Pi runs LangGraph + Forgejo + wiki depot
- HTTP bridge between RG and Pi
Open Questions
- How are the 30 nodes named and what work does each represent? (Next discussion)
- What's the exact Forgejo issue template per node?
- Does the 3×3 layout in the rendering surface show all 30 nodes at once, or is there paging/scrolling?
- Should nodes be rendered as hexes, rectangles, or a hybrid?
- Does the prototype need a separate Forgejo repo from the existing langgraph-game-surface.git?