solo-journaling/.agents/skills/run-session/SKILL.md

name, description

name	description
run-session	Run a turn or a full session of a solo journaling campaign. Use when the player describes what their character does, asks to start or continue a session, or asks what happens next. Interprets the message as in-fiction intent, rolls through the journal CLI, narrates the outcome in chat, appends it to the session log, and updates the PC sheet, clocks, threads, and world files.

Running a session

The player types their intent into chat, exactly as they would request a code change. Everything else is your job: resolve it with dice, narrate, and persist the result to the campaign's files. AGENTS.md holds the contract; this skill is the procedure for a single turn.

The player never edits files. If you narrated it, write it down.

1. Bootstrap the session

Do this once, before the first turn.

1. Identify the campaign. journal games lists games; the campaign is campaigns/<name>/. If the player named one, use it. If several exist and they did not, ask — do not guess. Only campaigns/ directories without a leading _ count.
2. Read the campaign's game from campaigns/<name>/campaign.md frontmatter (game: <id>). Read games/<id>/game.md — it is authoritative — plus campaigns/<name>/house-rules.md.
3. Load state. Read the PC sheet(s) in characters/, state/clocks.md, state/threads.md, and the tail of the newest sessions/NNNN-*.md.
4. No PC yet? Build one from the game's characters/ options (roll them with journal <command> where the game provides one), write the sheet to campaigns/<name>/characters/<pc>.md, and say what you created.
5. Pick the session file. Continue the newest one, or start the next: NNNN is the previous number plus one, zero-padded to four digits, with a kebab-case slug from the opening situation. Use templates/session.md.

2. Read the player's message

• In-fiction intent — the player describing what the PC does, tries, or asks. This is the main case: go to step 3. Record their words verbatim in the Player block.
• Meta request — a rules question, a recap, "what are my stats?", "start a session". Answer from the files. Do not roll, do not append a scene, and do not treat it as intent.

When a message is ambiguous, answer the meta part and ask whether they want the action attempted.

3. Decide whether to roll

Roll only when the outcome is genuinely uncertain and both results would be interesting. Do not roll for trivial actions, for what the fiction already settles, or to decide what the PC wants.

• Oracle — a yes/no question about the world: "Is the gate locked?" Ask one question at a time, phrased so either answer is interesting.
• Spark table — generating content: a location detail, an NPC's trait, what happens next.
• Complication — on and/but results, or when the fiction needs a twist.
• The game's own resolution — if game.md defines one, follow it and use journal dice for its rolls, or the game command it provides.

If the game ships a command for what you are about to do, use the command rather than reimplementing it by hand.

4. Roll

Always pass --campaign <name>. Use the CLI's output exactly as printed — it already renders the oracle's label, so relay that rather than re-deriving it.

journal oracle "Is the gate locked?" --complicate --campaign ashfall
journal roll sparks --campaign ashfall
journal dice 2d6+1
journal <game-command> --campaign ashfall

Never invent, reroll, or adjust a result. If a roll is not interesting, the mistake was calling for one — narrate from the fiction instead.

5. Narrate and append

Resolve the intent into a concrete outcome, then append one scene to the current session log using the format in AGENTS.md. Copy templates/session.md for a new file.

• If you rolled, put the CLI output in backticks, verbatim.
• Omit the roll line when no roll was needed.
• List every mechanical change on the State line.
• Reply in chat with the same resolution prose, so the player can read it without opening the file. Keep chat and file consistent.

6. Apply state changes

The scene is not finished until the files match the State line.

Change	File
Stat, track, condition, inventory	campaigns/<name>/characters/<pc>.md frontmatter
A clock filled or advanced	campaigns/<name>/state/clocks.md
A thread opened, resolved, abandoned	campaigns/<name>/state/threads.md
A place, person, or faction first appears	new file under world/
Something changes about an existing one	that file
A rule shape that emerged in play	campaigns/<name>/house-rules.md

Never invent stats the game does not use. Keep the frontmatter shape the game defines.

Continuity rules

• Append only. Never edit a past scene except to fix a typo the player points out.
• Do not decide what the PC wants. The oracle answers the world; the player answers the character.
• Never copy game content into a campaign. Reference the game package.
• Keep frontmatter and prose consistent. If the log says a stat changed, the sheet must show it.

Closing a session

When the player stops for the night:

1. Run journal check --campaign <name> and fix anything it reports.
2. Make sure every State line has been applied.
3. Leave state/threads.md reflecting what is unresolved.

Common failures

• Inventing a dice result, or rolling without calling the CLI.
• Rolling when the fiction already answers the question.
• Paraphrasing the player in the Player block instead of quoting them.
• Writing a State line but not applying it to the files.
• Editing an earlier scene to "fix" continuity instead of writing the fix forward.
• Acting on the wrong campaign when several exist — ask first.