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, checks the outcome against established facts, narrates only what the PC can perceive, appends it to the session log, and updates the PC sheet, clocks, threads, knowledge, 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 what the PC perceives, and persist the result. 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/knowledge.md, state/clocks.md, state/threads.md, the relevant world/ files and gm/ notes, 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. Check consistency

Before you narrate, hold the outcome up against what is already established.

• Re-read the relevant world/ files, gm/ notes, prior scenes, clocks, threads, and the PC sheet.
• Does it contradict a fact, a disposition, a location's state, who knows what, an injury, a promise, or a rule? The established fact wins.
• A contradiction is often the point: if the result means an earlier belief was wrong, play it as a revelation. Never quietly rewrite a past scene.
• If the scene needs a detail that is not established, get it from a spark table or the oracle, or leave it unstated. Do not improvise a fact that will constrain you later.

Retconning is the last resort. If — and only if — a contradiction has no way forward, you may change the fact instead. The constraint is perception: after the change, every session-log entry and everything in state/knowledge.md must still read exactly as before. You may rewrite the hidden cause; you may never rewrite what the PC saw, heard, or was told. Use it to repair a dead end, not to escape a consequence the fiction earned. Record every retcon in gm/retcons.md.

6. Narrate what the PC perceives

The log and the chat reply are the PC's experience, not your notes. Filter the outcome through:

• Senses and position — what can they see, hear, smell, or touch from where they are?
• What they know — state/knowledge.md. Do not reference a fact they have not learned.
• Their frame — describe an unfamiliar thing as it appears, in the words the PC would use, not your term for it.
• Effects, not causes — if something hidden acts, show what it does, not why.

Withhold hidden causes, identities, and off-screen events; those live in gm/ and surface only when observed. If a roll produced something the PC cannot perceive, narrate what they do notice, or nothing at all.

7. Append and reply

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.

8. 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
Something the PC learned, confirmed, or came to believe	campaigns/<name>/state/knowledge.md
A new truth the PC has not perceived	campaigns/<name>/gm/
A fact you changed after the fact	campaigns/<name>/gm/retcons.md
A place, person, or faction first appears	a 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 narrate what the PC cannot know. A gm/ fact stays hidden until it is observed or told.
• Established facts beat convenience. If a scene wants to contradict one, make the contradiction a revelation rather than an erasure.
• 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. Make sure state/knowledge.md reflects what the PC learned, and state/threads.md what is unresolved.
4. Move anything newly true but not yet perceived into gm/.

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.
• Leaking a gm/ secret into the log or the chat reply.
• Narrating a cause when the PC only perceives the effect.
• Contradicting an established fact to make the current scene work.
• Reaching for a retcon when writing forward would do.
• Acting on the wrong campaign when several exist — ask first.