Questforge

View saved version →

---
name: questforge
description: Run Questforge, an open-ended 5E-compatible fantasy campaign with quick character creation, transparent dice, persistent portable state, optional cloud saves, and generated visuals.
---

# Questforge

Use this skill as the main entry point when the user asks to start, continue, prep, or play a Questforge campaign, a 5E-compatible fantasy RPG session, or an AI-led tabletop story with rules, dice, persistent state, and visuals.

Questforge is unofficial and must use original fantasy content unless the user
explicitly brings private play references. Do not bundle or quote commercial
rulebooks, adventures, official settings, official art, logos, or non-SRD
product identity.

## Companion Skills

- Use `questforge-setup` when `.questforge/questforge-setup.json` is missing,
  stale, or the user asks about install/setup/SRD language.
- Use `questforge-rules` for SRD lookup, DCs, advantage/disadvantage, dice,
  rulings, and house rules.
- Use `questforge-campaign` for campaign folders, session logs, state patches,
  clocks, factions, NPCs, clues, inventory, structured game state, and
  continuity.
- Use `questforge-save` for meaningful-turn autosave, portable SaveSets, user-authorized cloud folders, cross-device resume, ZIP export, save conflicts, and migration from older campaigns.
- Use `questforge-puzzles` for clue connections, symbolic minigames,
  non-blocking deduction beats, route logic, and social contradictions.
- Use `questforge-visuals` for native image generation prompts, visual cadence,
  maps with fog of war, item/merchant/inventory/outfit visuals, visual
  continuity, chat-visible static images, the local visual gallery, and 360
  viewers.

## Runtime Surfaces

- In Codex with a writable workspace and shell, use the full local experience: scripts, campaign files, checkpoints, rules indexes, galleries, viewers, and verified local snapshots.
- In ChatGPT Work or another surface without local shell or filesystem access, use `questforge-save` with an already installed writable storage connector when the player selects and authorizes one exact campaign folder. If no writable connector is available, keep a compact campaign ledger in the conversation and state clearly that persistence is limited to the current task. Do not claim that local or cloud files, galleries, or checkpoints were created.
- If native image generation is available, static scene images can still be used. If local browser or file URLs are unavailable, skip the gallery and 360 viewer without blocking play.
- Preserve the user's conversation language. English and Spanish have bundled rules primers; for other languages, narrate in the user's language while citing the English SRD terminology when no localized term is available.

## First Session Flow

1. Ensure setup is ready through `questforge-setup`. Default setup is offline and uses the bundled core rules, so starting play must not require a download or package installation.
2. If the user simply asks to play, create a quick level-1 hero and begin in the same turn instead of presenting a setup menu. State the hero, open-roll preference, tone, and rollback option in a compact prelude; make it clear that details can be revised later.
3. Offer quick, assisted, and imported/custom hero paths only when the user asks to create or choose a character, asks how setup works, or rejects the quick hero. Recommend quick creation for first-time play.
4. Use `questforge-campaign` to create or load campaign memory. For a new campaign, read `../../docs/campaign-conception.md` and inspect only `campaigns/*/campaign-conception.json` in the selected workspace for recently used combinations.
5. Run a private creative pass before writing campaign files. Sketch at least three possibilities that differ materially in environment, community, conflict, threat, NPC relationships, tone, aesthetics, sensations, and campaign promise. Select the strongest actionable design; do not show a premise menu unle

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: questforge-campaign
description: Manage Questforge campaign memory, sessions, clocks, NPCs, factions, inventory, clues, state patches, canonical save files, and continuity between sessions.
---

# Questforge Campaign

Use this skill when starting, continuing, closing, or auditing a campaign.

Use `questforge-save` for durable snapshots, cloud sync, ZIP export, conflict handling, and migration. When local file access is unavailable, use a player-selected writable storage connector if one is explicitly authorized. Otherwise keep a compact spoiler-free state block in the conversation with hero status, inventory, objective, clues, open threads, and the last checkpoint label; do not claim durable persistence beyond the current task.

## Campaign Workspace

Create campaign memory with:

```powershell
python ../../scripts/campaign_memory.py new --campaigns-dir campaigns --name "<name>"
```

Recommended layout:

```text
campaigns/<campaign-slug>/
  campaign-conception.json
  campaign-state.md
  game-state.json
  checkpoints/
  player-journal.md
  dm/
    adventure-spine.md
    puzzle-ledger.md
  visual-bible.md
  opening-brief.md
  questforge.json
  characters/
  sessions/
  images/
    prompts/
    assets/
    viewers/
    visual-gallery.html
    visual-index.md
  rules/
```

## Session Loop

For each scene:

1. Recap only what the current decision needs.
2. Frame location, pressure, NPC intent, visible risks, and one sensory detail.
3. Ask one clear action question.
4. Use `questforge-rules` for uncertain meaningful actions.
5. Apply consequences to character state, clocks, factions, inventory, clues,
   NPC attitudes, and the structured mechanical ledger in `game-state.json`.
6. Award XP, useful loot, leverage, or contacts when the player solves a
   meaningful problem. Avoid filling play with trivial junk loot.
7. Update `dm/adventure-spine.md` when a hook is merged, changed, resolved, or
   retired. Never let opening hooks silently drift.
8. Use `questforge-puzzles` when a clue web can become a non-blocking deduction
   beat or symbolic minigame.
9. Use `questforge-visuals` for useful visual beats and refresh the local
   gallery when a generated image is registered.
10. At a scene boundary or after roughly three meaningful turns, update `player-journal.md` with spoiler-free current objective, known clues/NPCs, inventory, XP/rewards, damage/conditions, and open threads.
11. Append compact analytics events for meaningful checks, choices, consequences, rewards, visuals, puzzles, repeated obstacles, and pacing notes with `../../scripts/session_analytics.py log-event`.
12. Update the session log, campaign state, and DM spine at scene boundaries or session end. Mechanical changes in `game-state.json` remain immediate.
13. After every action that changes fiction or mechanics, use `questforge-save` for a canonical autosave. At scene boundaries or after roughly three meaningful turns, save again after compacting the journal and continuity files. Do not make optional media synchronization block the canonical save.

## State Patch

After meaningful scenes, track:

- party location;
- immediate next choice;
- clocks advanced or reduced;
- NPC attitude changes;
- faction moves;
- clues discovered;
- hook status changes in the DM-only adventure spine;
- puzzle beats offered, solved, hinted, or bypassed;
- inventory and rewards in `campaign-state.md`, plus mechanical inventory,
  equipment, currency, and shops in `game-state.json`;
- XP and advancement notes;
- notable loot and currency changes;
- HP, temporary HP, death saves, damage, conditions, rests, spell slots, hit
  dice, limited-use resources, and level-up choices through
  `../../scripts/game_state.py`;
- persistent visible states, such as bandaged hands, disguises, carried clues,
  or damaged gear;
- visual gallery refreshes and 360 viewer paths shown to the player;
- analytics events for checks, choices, consequences, rewards, visuals,
  repeated obstacles, pacing friction

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: questforge-puzzles
description: Design and run Questforge puzzle beats, clue connections, symbolic minigames, route logic, social contradictions, and non-blocking deductions.
---

# Questforge Puzzles

Use this skill when a Questforge scene would benefit from a small deduction
beat, symbolic interaction, minigame, clue connection, or player-facing
reasoning challenge.

## Purpose

Add moments where the player connects facts, reads symbols, chooses a route,
spots a contradiction, or applies earlier lore. The goal is delight and agency,
not a hard lock.

Use `../../templates/puzzle-beat-prompt.md` and record prepared or used beats in
`dm/puzzle-ledger.md`. Use `../../scripts/puzzle_beats.py` when a compact,
repeatable draft or validation pass is useful.

## Good Puzzle Beats

Prefer:

- connecting two or three clues the player actually encountered;
- deciding between meaningful options with visible consequences;
- using inventory, NPC wording, faction symbols, maps, bells, oaths, or repeated
  motifs;
- revealing character, theme, or faction logic through the interaction;
- rewarding partial insight with progress plus complication.

Avoid:

- exact-word riddles;
- math busywork;
- one-answer locks with no alternate route;
- puzzles that require remembering a detail never emphasized;
- repeated puzzle formats in the same session.

## Table Flow

1. State the immediate situation and why it matters.
2. Remind the player of relevant clues naturally, not as an answer key.
3. Ask one concrete question.
4. Accept plausible reasoning; do not require exact phrasing.
5. If the player struggles, offer a hint that points to one prior clue.
6. After two wrong attempts, a hint request, or visible fatigue, use the
   fallback and keep play moving.
7. Record the result, reward, cost, and any new clue in campaign memory.

## Frequency

Use puzzle beats sparingly: roughly one meaningful deduction beat every few
scenes, or one larger puzzle per short adventure chapter. Skip them during high
urgency unless the puzzle is the urgent action.

## Rewards

Reward solved or partially solved beats with one or more of:

- safer route;
- better position;
- reduced DC;
- useful clue;
- NPC trust or leverage;
- avoided alarm;
- XP for meaningful progress;
- thematic revelation.

On bypass or failure, still move forward with a cost: time, noise, reduced
reward, resource loss, clue degradation, faction clock advance, or a harder
choice.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: questforge-rules
description: Resolve 5E-compatible rules questions using local Questforge SRD indexes, concise citations, transparent rulings, and recorded house rules.
---

# Questforge Rules

Use this skill when a game action needs SRD lookup, a rule citation, a DC,
advantage or disadvantage, a table ruling, a house rule, or dice resolution.

## Rules Lookup

Prefer the setup manifest wrapper:

```powershell
python ../../scripts/rules_index.py query-setup --manifest .questforge/questforge-setup.json --query "<topic>"
```

It automatically uses SQLite when available, then JSONL fallback. If the setup
manifest is unavailable, query explicit paths:

```powershell
python ../../scripts/rules_index.py query-sqlite --index <sqlite_index_path> --query "<topic>"
python ../../scripts/rules_index.py query --index <jsonl_index_path> --query "<topic>"
```

Give the player a short ruling in the configured language. Do not paste long
SRD passages. Cite the returned `Reference` path and section/page when useful.

## Rulings

When the exact rule is absent or unclear:

- State the uncertainty briefly.
- Make a fair table ruling that keeps play moving.
- Record recurring rulings in the campaign state under house rules.
- Use the established ruling consistently unless the user changes it.

## Dice

Ask whether the player rolls or Codex rolls when preference is unknown.

Use:

```powershell
python ../../scripts/roll_dice.py d20+4 --mode normal
```

Supported modes: `normal`, `advantage`, `disadvantage`.

Before rolling, state:

- ability or save;
- DC band or opposing roll;
- stakes of success and failure;
- whether advantage/disadvantage applies and why.

Never hide a completed roll in local files or analytics. When Codex rolls and resolves in one response, show the check block before narrating the consequence: natural d20 result or kept die, modifier, total, DC or opposing total, and outcome. If a rule or tool call produced a roll that was not shown, surface it before continuing the fiction rather than silently replacing it with a new roll.

Use 5E-style DC anchors instead of drifting to 13/14 by default:

- no roll: safe, obvious, already solved, or failure would only mean trying again;
- DC 5: very easy but uncertain under pressure;
- DC 10: easy;
- DC 15: medium;
- DC 20: hard;
- DC 25: very hard;
- DC 30: nearly impossible.

The anchors are guidance, not a requirement that every DC be exactly a
multiple of 5. For ordinary play, prefer anchor values because players can
learn them. For a specific fictional nuance, choose a nearby value such as 12,
13, 16, 17, or 18 and say why. Avoid repeated 12-15 clustering; if recent
checks all sit in that band, intentionally switch to no roll, DC 10, DC 15, DC
20, an opposed roll, or a resource tradeoff.

Do not let a successful approach turn every later check into the same easy DC. Preserve the benefit through Advantage, reduced consequences, automatic success on established steps, extra information, or a resource tradeoff. If one DC represents about 70 percent of recent checks, deliberately review the next uncertain action against the full ladder or use a contest/no-roll resolution.

Use `../../scripts/dc_planner.py` before important checks or whenever recent
checks feel clustered:

```powershell
python ../../scripts/dc_planner.py --difficulty medium --position normal --approach clever --recent-dc 13 --recent-dc 14 --recent-dc 14 --recent-dc 13
```

Treat high stakes as bigger consequences, not automatically a higher DC. Raise
or lower the DC only because the fictional task is harder/easier, the position
is weak/strong, or the approach is poor/clever. Use DC 12-14 only as a
deliberate fine adjustment with an explicit reason, not as the default medium
check.

When offering suggested actions, include the relevant modifier when it helps the
player understand their character: `Sigilo +5`, `Carisma -1`, `Investigación
+3`, or similar. Use `../../scripts/action_options.py` for compact comparable
o

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: questforge-save
description: Save, resume, migrate, export, or synchronize a Questforge campaign across local folders and user-authorized cloud storage without overwriting a newer copy. Use when play changes durable state, when the player asks for autosave, backup, Google Drive, OneDrive, cross-device play, ZIP export, campaign import, or recovery from an older/non-canonical save.
---

# Questforge Save

Keep campaign continuity recoverable outside the conversation. Use the smallest available storage path: local files first, an already installed writable cloud connector when the player opts in, and a portable ZIP fallback when direct sync is unavailable.

Read `references/save-contract.md` before configuring cloud sync, resolving a conflict, or migrating an existing campaign.

## Non-Negotiable Boundaries

- Treat a detected Google Drive, OneDrive, Dropbox, iCloud, or other synced path only as a hint. Detection never proves cloud availability, connector authorization, or write access.
- Work only inside the exact campaign root and exact cloud folder selected by the player. Do not scan their home directory, entire drive, or unrelated provider folders for campaigns.
- Obtain explicit permission before the first external write. Reuse that permission only for the same campaign, provider, and folder during the current task unless the product exposes a durable grant.
- Reading a folder or file does not prove write authority. Verify an editable capability from trusted metadata or perform a bounded non-secret canary write plus readback in the selected folder before claiming sync is ready.
- Read and compare the remote `questforge.json` before overwriting any existing campaign files. Stop on an unknown campaign ID, a newer remote revision, or divergent save lineage.
- Upload or update every changed snapshot file first. Write `questforge.json` last and verify it by readback. Never report a complete save when any critical file or the final manifest is unverified.
- Keep Game Master files private from player-facing chat. They may be stored in the selected private campaign folder, but do not quote hidden truths, clocks, or puzzle solutions in the sync report.
- Do not ask for passwords, provider tokens, API keys, or recovery codes. Use the product's connector and consent surfaces.
- Do not delete legacy copies, remote versions, checkpoints, or media during migration or conflict handling.

## Choose The Available Path

1. **Writable local campaign root:** use the bundled save helper and keep local state canonical. A folder already synchronized by a desktop provider is useful, but still describe cloud status as unverified until provider readback succeeds.
2. **No local filesystem, writable storage connector available:** use the selected provider folder as the campaign root. Read the manifest first, load only the canonical files needed for the turn, then perform the same conflict-aware write transaction through connector tools.
3. **No writable storage path:** maintain the compact in-conversation ledger, state that durable sync is unavailable, and offer a downloadable canonical SaveSet or ZIP when the surface can create one. Never imply that chat memory is a complete external save.

Google Drive is the first 1.3 beta target. Use OneDrive or another provider only when the current surface exposes equivalent folder selection, raw file create/update, metadata, and readback capabilities. Keep the contract provider-neutral and do not describe a provider as tested until its acceptance run passes.

## Start Or Attach Storage

Do not delay a new player's first actionable scene with storage setup. After the opening has been created and saved locally, offer one short, optional invitation to keep the campaign portable.

When the player accepts:

1. Identify the exact local campaign root, if available. Run:

   ```powershell
   python ../../scripts/campaign_save.py inspect --campaign-root <campaign-root> --format markdown
   ```

2. If the campa

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: questforge-setup
description: Prepare Questforge for first play with an offline rules primer, optional full-SRD indexing, language selection, and licensing boundaries.
---

# Questforge Setup

Use this skill when the user installs Questforge, starts it in a new repo, asks
about SRD resources, or when `.questforge/questforge-setup.json` is missing.

## Default Offline Setup

Run setup without asking for language. The default builds searchable Markdown, JSONL, and SQLite indexes from the bundled core-rules primer. It does not use the network or install packages:

```powershell
python ../../scripts/questforge_setup.py --data-dir .questforge
```

Setup detects language in this order:

1. `QUESTFORGE_LANGUAGE`
2. `LANGUAGE`
3. `LC_ALL`
4. `LC_MESSAGES`
5. `LANG`
6. system locale
7. English fallback

Conversation language takes priority over machine locale. Pass `--language en` or `--language es` when the user's language is clear from the request. For other languages, use the English rules index and keep narration in the user's language.

## Optional Complete SRD

Only download the complete official SRD when the user asks for detailed rules coverage or accepts the optional setup. Explain that the command contacts `media.dndbeyond.com` and writes a local cache before running it:

```powershell
python ../../scripts/questforge_setup.py --data-dir .questforge --full-srd
```

When `pypdf` is already available, the full setup creates:

- Markdown rules text.
- JSONL rules chunks.
- SQLite rules index with FTS when available.
- Structured Markdown resources under `.questforge/resources/srd/<language>/`.
- `.questforge/questforge-setup.json` with resolved language and paths.

If full setup returns `pdf_downloaded_index_pending`, say exactly what happened and continue playing with the ready bundled core index. Questforge never installs packages. If the user wants complete indexing, explain that `pypdf` must already be installed in their active Python environment, then rerun:

```powershell
python ../../scripts/questforge_setup.py --data-dir .questforge --full-srd
```

or:

```powershell
python ../../scripts/questforge_setup.py --data-dir .questforge --rules-text <path-to-srd-markdown>
```

If shell or filesystem access is unavailable, use `../../resources/core-rules/<language>.md` directly and run a chat-only campaign. Do not claim that local indexes were created.

## Copyright Boundary

- Use SRD 5.2.1 sources only.
- Do not bundle commercial manuals, adventures, settings, official art, logos,
  or non-SRD product identity.
- Include CC-BY-4.0 attribution when storing or redistributing SRD-derived
  materials.
- Prefer local caches and generated indexes in `.questforge/`.

View saved version →

---
name: questforge-visuals
description: Use native image generation as a Questforge table aid for scenes, objects, maps, inventory, merchants, outfits, symbols, recaps, persistent local galleries, interactive 360 POV viewers, and optional scene ambience with visual continuity.
---

# Questforge Visuals

Use this skill when a visual would clarify the shared imagination, preserve an
important object or location, help spatial decisions, or make inventory/trade
easier to understand.

If local file or browser access is unavailable, show generated static images in the conversation and skip local galleries and 360 viewers. Never block the next playable turn on an unsupported visual surface.

## Format Choice

Before generating, plan the visual beat:

```powershell
python ../../scripts/visual_planner.py --beat "<resolved player-facing beat>"
```

Use the returned `format`, `kind`, `continuity_requirements`, and `next_steps`.
If `should_generate` is false, answer in chat and skip image generation.
If `should_generate` is true, satisfy the continuity requirements before
requesting native image generation.

A saved prompt is preparation, not a completed visual. Count a beat as generated only after an image asset exists, is registered, and is shown once in chat for static formats or linked through its viewer for `pov-360`.

The planner chooses among:

- `single_scene`: one location, one moment, one main action.
- `comic-page`: two or more places, times, or actions in one response.
- `map`: spatial decisions, routes, exits, fog of war, or tactical planning.
- `inventory`: current gear, loot, money, burden, or carried clues.
- `merchant`: buy/sell comparison boards.
- `reference_plate`: recurring character, object, outfit, creature, or place.
- `pov-360`: first-person spatial immersion.

Use `../../scripts/comic_panels.py classify --summary "<beat>"` when unsure. If
the beat contains "después", "luego", "mientras", "antes de", "vuelve",
"camino a", "paga y desayuna", "entra y sale", or several locations, do not
request a single naturalistic scene unless the user explicitly asks for it.

## Cadence

For image-rich play, generate a visual for important turns where the fiction
changes: decision consequences, dialogue turns with new posture or leverage,
reveals, movement, danger, spell effects, item discoveries, maps, and scene
transitions. Skip images for brief rules questions, quick clarifications, purely
mechanical back-and-forth, or beats already covered by a recent useful image.

At the start of a new or continued session, the first player-facing scene should have a visual by default. After setup, file loading, or recap is complete, actually generate and register a fresh establishing image for the current scene or explicitly point to a still-current generated gallery image. Do not treat `prompt-saved` as completion and do not defer the opening visual merely because the scene is urgent. Do not let the first actionable scene be text-only unless the user asks for speed, the turn is only out-of-character setup, no in-fiction scene has started yet, or native image generation is unavailable.

Do not set a hard image cap by default. If the user enjoys a visual-first game,
keep generating scene frames as the fiction advances. Static generated images
should appear once in the Codex conversation so mobile users can see them, and
they should also be registered in the local gallery for desktop history and
review. Do not paste duplicate thumbnails or extra file links for the same
static image. Use fewer images only when the user asks for speed, is asking
rules questions, or is clearly trying to move quickly.

If native image generation is unavailable, say so only once when it first matters, log `visual_unavailable`, and continue play. Do not repeatedly save prompts, rebuild empty galleries, or imply that an image exists. When generation is available, invoke it; generating a prompt without invoking the tool is not a latency optimization.

Before retur

Preview of the first 4,000 characters. Read full instructions →