/story-tree: Story Tree Builder

Created by IOTA - Joseph Bryant. https://iotallc.github.io/

This file is a skill guide. It tells the model in IOTA how to do the job step by step. It is not a compiled program and it does not install anything. To use it, paste its text into an IOTA chat and then give your request, or read it and follow the steps yourself.

Purpose

Plan and write branching dialogue: scenes, characters, choices, and endings stored as a JSON file a game or interactive story can load, plus a visual map of every branch. The skill keeps the tree valid (no dead links, every path reaches an ending) and keeps content safe for work.

When to use

• Writing a choose your own path story, a game conversation, or a training scenario with choices.
• Mapping an existing story to find dead ends and loose threads.
• Producing dialogue data for a game engine.

When not to use

• Linear stories with no choices.
• Adult or graphic content. This skill only writes content suitable for all audiences (see the content rules).

Requirements

• Python 3.10 or later. Graphviz (dot) for PNG and SVG maps, or none if you only need the Mermaid map.
• Model: Gemma 3 12B or 27B or a Nemotron model keeps characters and tone consistent across many scenes. Gemma 3 4B can write short trees (under 20 scenes) if each scene is generated with the summary of its path.

Inputs

Content rules (SFW)

The skill applies these to every scene and choice and refuses requests outside them: - No sexual content, nudity, or romantic content involving minors. - No graphic violence or gore. Danger and conflict are fine when described without graphic detail. - No hate speech or slurs, and no content that demeans people for who they are. - No instructions for real world harm (weapons, drugs, hacking). - No real living people as characters without the user confirming it is respectful and fictional. - Self harm is never presented as a choice. If a request breaks a rule, the skill says which rule and offers an alternative direction.

Data format

{
  "title": "Night Shift",
  "version": 1,
  "credit": "Built with the /story-tree skill guide by IOTA - Joseph Bryant",
  "start": "s1",
  "characters": {
    "mara": {"name": "Mara", "role": "night shift engineer"},
    "unit7": {"name": "Unit 7", "role": "assembly robot"}
  },
  "variables": {"trust": 0},
  "scenes": {
    "s1": {
      "text": "The line is silent. Then Unit 7 speaks: \"Are you the one who fixes things?\"",
      "speaker": "unit7",
      "choices": [
        {"label": "Answer it", "next": "s2", "effects": {"trust": 1}},
        {"label": "Call the supervisor", "next": "s3"}
      ]
    },
    "s2": {"text": "...", "choices": [{"label": "...", "next": "e1", "requires": {"trust": 1}}]},
    "s3": {"text": "...", "choices": [{"label": "...", "next": "e2"}]},
    "e1": {"text": "...", "ending": "good"},
    "e2": {"text": "...", "ending": "neutral"}
  }
}

Step-by-step procedure

1. Outline first. Propose the structure before writing scenes: acts, the main decision points, and the endings. Use a branch and merge shape (paths split, then rejoin at key scenes) to keep the size manageable. Ask the user to approve or change the outline.

2. Write scenes one at a time, each with the path so far:

   Story: {title}. Premise: {premise}. Audience: {audience}. Style: {style}.
   Characters: {character notes}
   Path so far (summaries): {summaries}
   Write scene {id}: {outline line}. 40 to 120 words of narration and dialogue.
   Then 2 or 3 choices, each under 8 words, each leading to {allowed next ids}.
   Follow the content rules. Return JSON for this one scene only.

3. Validate the tree after every few scenes.

   import json
   from collections import deque
   
   def validate(story: dict) -> list[str]:
       errs, scenes = [], story["scenes"]
       if story["start"] not in scenes:
           errs.append(f"start {story['start']} missing")
       for sid, s in scenes.items():
           has_choices, is_end = bool(s.get("choices")), "ending" in s
           if has_choices == is_end:
               errs.append(f"{sid}: needs choices or an ending, not both or neither")
           for c in s.get("choices", []):
               if c["next"] not in scenes:
                   errs.append(f"{sid}: choice '{c['label']}' points to missing {c['next']}")
               for var in list(c.get("effects", {})) + list(c.get("requires", {})):
                   if var not in story.get("variables", {}):
                       errs.append(f"{sid}: unknown variable {var}")
       seen, q = {story["start"]}, deque([story["start"]])
       while q:
           for c in scenes.get(q.popleft(), {}).get("choices", []):
               if c["next"] in scenes and c["next"] not in seen:
                   seen.add(c["next"]); q.append(c["next"])
       errs += [f"{sid}: unreachable" for sid in scenes if sid not in seen]
       # every scene must be able to reach an ending
       ends = {sid for sid, s in scenes.items() if "ending" in s}
       can_end, changed = set(ends), True
       while changed:
           changed = False
           for sid, s in scenes.items():
               if sid not in can_end and any(c["next"] in can_end for c in s.get("choices", [])):
                   can_end.add(sid); changed = True
       errs += [f"{sid}: no path to an ending" for sid in scenes if sid not in can_end]
       return errs

   Also check that no scene has all its choices locked by requires on every path. A simple check: if every choice in a scene has requires, flag it for review.

4. Draw the map. Mermaid (works in many Markdown viewers) and Graphviz for an image:

   def to_mermaid(story):
       out = ["flowchart TD"]
       for sid, s in story["scenes"].items():
           label = s["text"][:40].replace('"', "'")
           shape = f'{sid}(["{label}"])' if "ending" in s else f'{sid}["{label}"]'
           out.append(f"  {shape}")
           for c in s.get("choices", []):
               out.append(f'  {sid} -->|{c["label"][:24]}| {c["next"]}')
       return "\n".join(out)
   
   def to_dot(story):
       lines = ["digraph story {", '  rankdir=TB; node [shape=box, style="rounded,filled", fillcolor="#F2F2F2", fontname="Segoe UI"];']
       for sid, s in story["scenes"].items():
           fill = "#CFE8D5" if s.get("ending") == "good" else "#F4C7C3" if s.get("ending") == "bad" else "#F2F2F2"
           label = json.dumps(f"{sid}: {s['text'][:40]}")
           lines.append(f"  {sid} [label={label}, fillcolor=\"{fill}\"];")
           for c in s.get("choices", []):
               lines.append(f"  {sid} -> {c['next']} [label={json.dumps(c['label'][:24])}];")
       lines.append("}")
       return "\n".join(lines)

   Render: dot -Tpng story.dot -o story-map.png and -Tsvg for a zoomable version.

5. Content review pass. Re-read every scene against the content rules and list any line that needs a change, with a suggested rewrite. Apply only after the user agrees.

6. Play test. Print every path from start to each ending as a numbered list of choices so the user can read them like a reader would.

Output format

• story.json
• story-map.md (Mermaid), story.dot, story-map.png or .svg
• paths.txt with every path
• Chat summary: scene count, endings by type, longest and shortest path, validation result.

Safety and confirmation rules

• Content rules above are always on.
• Never overwrite an existing story.json; save story.v2.json and show the differences.
• Never delete scenes without asking; unreachable scenes are reported, not removed.
• Nothing is published or shared.

Quality checks

• validate() returns no errors.
• Every choice label is distinct within its scene.
• Character names and voices stay consistent (the skill checks each speaker id exists).
• Each ending is reachable.

Examples

1. "Night Shift" premise, 15 scenes, 3 endings: outline, scenes, valid JSON, PNG map with endings colored.
2. Map mode: an existing 40 scene JSON with 2 dead links and 1 unreachable scene; the skill reports them and draws the map.
3. Training scenario: a customer service conversation with a trust variable that unlocks a better ending.

Troubleshooting

Limitations

• The map is readable up to about 60 scenes; larger trees are split by act.
• Variables are simple counters; no strings or complex logic.
• Writing quality depends on the model size.

Changelog

• 1.0 (October 2026): First release. Outline first workflow, JSON format with variables, validator, Mermaid and Graphviz maps, SFW content rules.