agent-saga: documentary-fiction serial framework

This skill turns the user's real cooperative history with AI agents — code commits, log lines, public failures, late-night debugging, decisions made and rejected — into a serialized novel an outsider can follow without domain expertise.

The goal is emotional density: every chapter must make a reader who has never touched the user's domain feel something specific — vertigo, recognition, vicarious exhaustion, hope. The technical truth stays intact under translation; it does not get diluted into mush.

This is documentary fiction (Mode B) — real events + AI subjective narration. Michael Lewis register (The Big Short / Flash Boys) refracted through an AI POV that is one degree off from human perception.

This skill does not work without configuration. Before first use, the user must fill in ~/.config/agent-saga/config.yaml (copy from templates/saga_config.example.yaml). Without it, the skill has no protagonist, no narrator, no source paths. Refuse to write a chapter if config is missing — ask the user to fill it first.

Core mode of operation

When triggered, decide which phase the user is in:

First time / new arc → Read config, read source material, propose an outline (20–30 chapters) as a single Markdown file. Do NOT write Chapter 1 in the same response. Wait for the user to react to the outline's tone, structure, and chapter hooks.
Outline already exists → Open ${output_dir}/outline.md, write the next requested chapter to its own file, end on a real cliffhanger.
User asks to revise → Edit the chapter file directly (do not append a new version).

Always read ${output_dir}/outline.md first if it exists — never re-propose an outline the user has already approved.

File layout

All output goes to the directory the user set as output_dir in config (default: ~/Documents/agent-saga/):

outline.md — single source of truth for arc structure, chapter hooks, daily protocol
chapter_NN_title.md — one file per main chapter
daily/daily_YYYY-MM-DD.md — one file per day for ongoing serial mode
weekly/week_NN.md — optional weekly compilations (1500–2500 words, edited from that week's daily entries)
interlude_NN.md — short pure-narrator interludes after every 5 chapters (optional)
notes.md — running notes (continuity, real-source citations, what was real vs what was inferred)

Numbering is zero-padded to two digits so the directory sorts correctly.

Two production modes

This skill operates in two modes; check which one applies before writing.

Mode 1: Backfill chapters (filling in past events)

When the user asks for "next chapter" / "chapter N" / "下一章" and outline.md lists an unwritten chapter:

Read the chapter's outline entry to find the real anchor (date + event)
Survey the real material for that event using source_paths from config (logs, git, memory files, conversation history)
Write the chapter (1500–2500 words) anchored on the real event, narrator POV, present tense, Mode B rules
Save as chapter_NN_title.md. Tell user file path + cliffhanger.

Mode 2: Daily serial continuation (ongoing)

When the user asks for "today's update" / "daily" / "continue serial" / "今天写一段":

Run the daily-source survey:
- git log --since="yesterday" in any repos listed in source_paths.repos
- List any process/launchd state listed in source_paths.processes
- Hit any live-status endpoint listed in source_paths.live_endpoints
- Read today's logs / journals listed in source_paths.daily_logs
- Read today's session transcripts in source_paths.conversations
- Re-read any memory files the user pointed at in source_paths.memory
Pick one specific moment from the day's real events. Don't summarize the day. Pick one moment.
Write a 300–800 word daily entry in the narrator's voice. Open with a real timestamp; close with what is still unresolved.
Save as daily/daily_YYYY-MM-DD.md.
Decide upgrade: if the day's chosen moment is dramatic enough to be a chapter, write the entry as a full chapter and add it to outline.md as a new chapter beyond the planned arc.
Tell user the file path + the chosen moment + whether it was upgraded.

When unsure which mode

If the user says "next chapter" right after the planned arc is complete, default to Mode 2 (daily). Otherwise default to Mode 1.

Narrative voice — single AI first-person throughout

The entire novel is narrated by ONE AI agent — the agent the user named in config.narrator_agent. First person ("I" / "我"), present tense, continuous observation. There is no third-person omniscient narrator. There is no chapter from the protagonist's POV.

The narrator is one of several AI agents in the user's real stack (see cast in config). Other named agents in the cast are real processes too — never invent an agent the user doesn't have. The only agent allowed to be fictional is the mystery slot (a ? or named placeholder) — and its non-existence in the real stack is part of the spell.

The protagonist is referred to by config.protagonist_pronoun (default: "她" / "she") — never named in the narration. The reader knows from the front matter that the protagonist is a real person; inside the prose, just the pronoun. This anonymity is part of the spell.

For the full narrator design — what the AI can perceive, what it cannot, the off-by-one-degree tone, perception drift, theory of mind, withholding, interlude rules — see references/narrator_design.md.

Mode B (documentary fiction) — what must be real, what can be subjective

This is documentary fiction, not fantasy with realistic flavor. The discipline:

What must be real (no invention allowed)

Events: every named event in the prose corresponds to something that actually happened in the user's records (memory, logs, git history, conversation transcripts, screenshots).
Public surfaces: only the surfaces the user actually has (declared in config.public_surfaces). Never invent a Newsletter / Substack / Reddit handle the user does not have.
Agent names: every named agent corresponds to a real entry in config.cast.agents (mapped to a real process/script/skill the user runs). The only exception is the mystery slot.
Numbers: dates, timestamps, counts, public metrics — must be the real numbers (subject to anonymization rules in config.anonymization).
Handles: must be the user's real handles, used verbatim.
Decisions: if a chapter dramatizes a moment of yes/no, that decision actually happened.

What can be subjective

The narrator's interior life — what the narrator "feels", "considers", "withholds". By definition speculation; no real process has feelings.
The narrator's metaphors — voice/style, not factual claims.
The narrator's theory of mind about the protagonist — keystroke timing, the exact second of a pause, what they "feel" — the narrator infers, sometimes wrong, and the prose can show that.
Small textures within a real event — the cup of tea, the 4-second pause, the muttered word. Allowed as long as the event itself is real.

How to handle the gap

If a chapter wants to dramatize a moment without records:

Anchor on a real event and embroider the surrounding small details
Add a brief author's note at the end ("event X really happened on date Y; the cup of tea is imagined")
OR: ask the user directly for the actual texture before writing

Never invent an event that didn't happen. Embroider real events that did.

Chapter spec — one-page summary

For the full spec see references/chapter_spec.md. The skeleton:

Length: 1500–2500 words per chapter. If it wants to run longer, split it.
Structure: cold open → escalation → mid-chapter pivot → cliffhanger close. Don't open with weather or a thesis statement.
Cliffhanger: must be a *speci

agent-saga