Skip to main content

LLM Story Authoring Pipeline

Status: current committed story-layer governance lives in ../story/README.md, ../story/templates/story-entry-template.md, the five story indexes under ../story/indexes/, and ../lore/adr/ad-0003-story-content-layer-and-agent-audit.md. The story-specific skill layer is committed under .agents/skills/valenar-* and mirrored under .claude/skills/valenar-*. The story-specific read-only subagent layer is committed under .codex/agents/valenar-* and mirrored under .claude/agents/valenar-*. The committed deterministic validator lives at tools/valenar-story-audit/validate-story-docs.py with an optional shell wrapper at scripts/validate-valenar-story-docs.sh. Remaining drift is broader future authoring coverage, not validator absence; this file records the minimum pipeline contract so local agents do not collapse story drafting, reveal control, branch review, and canon promotion into one prompt.

Why Local LLM Agents Need This Structure​

Local LLM agents can draft readable prose quickly, but Valenar's story layer has four separate control problems: continuity, reveal ceilings, branch-state tracking, and canon-delta separation. A single writer prompt does not preserve those boundaries reliably. The pipeline therefore keeps story prose, truth-layer canon, and audit authority in distinct surfaces.

This structure is meant to survive future Valenar entries, future games, and both Claude-style and Codex-style local agents. The story layer must remain useful even when agent tooling changes, which is why this document points at the committed README, template, indexes, and ADR instead of redefining them.

Authority Split​

  • AGENTS.md and CLAUDE.md define repo-wide tenets, command references, and general agent behavior.
  • .github/copilot-instructions.md and .github/instructions/valenar-docs-wave.instructions.md govern the current docs-only Copilot workflow, including the existing explorer -> implementer -> verifier chain for docs/process waves.
  • ../lore/adr/ad-0003-story-content-layer-and-agent-audit.md establishes the story layer, the non-canon-by-default rule, and the required story / reveal / branch audits.
  • ../story/README.md is the authoritative story-layer contract for ownership boundary, required frontmatter, audit workflow, canon-delta flow, reveal-tier flow, and branch-ledger flow.
  • ../story/templates/story-entry-template.md is the reusable frontmatter and body skeleton for each entry.
  • The five files under ../story/indexes/ are the continuity ledgers that must be updated alongside accepted entries.
  • ../lore/pr-file-conventions.md remains authoritative for the lore tree only. Story files are outside that prefix-governed tree unless a future ADR changes the boundary.

Current Committed State​

  • The story layer under examples/valenar/docs/story/ is committed.
  • The entry template is committed.
  • The entity, timeline, reveal, branch, and canon-delta indexes are committed.
  • Dedicated structural validator automation is committed under tools/valenar-story-audit/validate-story-docs.py, with the thin wrapper scripts/validate-valenar-story-docs.sh.
  • Story-specific skills are committed: valenar-lore-extract, valenar-diary-entry, valenar-story-audit, valenar-reveal-audit, valenar-branch-ledger, and valenar-canon-delta.
  • Story-specific read-only subagent files are committed: valenar-story-auditor, valenar-reveal-auditor, valenar-branch-auditor, valenar-canon-librarian, and valenar-story-verifier.
  • A dedicated write-specialized story-author subagent remains deferred.
  • Canon promotion still happens outside the story layer in separate lore/design follow-up work.

Current Story Skill Layer​

The local pipeline now has reusable story-specific skills. They cover the capability split this document requires.

  • valenar-lore-extract: loads ADR 0003, the story README, the template, the story indexes, and the cited authorities before drafting or audit work.
  • valenar-diary-entry: drafts or revises one diary-entry artifact with explicit frontmatter, explicit canon_delta, explicit branch scope, and explicit downstream_hooks.
  • valenar-story-audit: performs the read-only structural story audit for frontmatter completeness, narrative coherence, source alignment, and acceptance readiness.
  • valenar-reveal-audit: performs the read-only reveal audit against the cited lh-*, ul-*, ud-*, gl-*, and caution-surface authorities.
  • valenar-branch-ledger: keeps branch scope, prerequisites, consequence surfaces, and ledger rows explicit; when explicitly asked to write, its scope remains limited to the target story file plus the required story indexes.
  • valenar-canon-delta: keeps canon_delta handling explicit and checks canon-delta-log coverage without updating truth-layer authorities inline.

Additional format-specific authoring skills can be added later, but the story skill layer is no longer purely deferred.

Subagents​

Current Committed Docs-Governance Chain​

  • explorer
  • implementer
  • verifier

These are the committed docs-only wave agents. They are not, by themselves, a complete story-authoring pipeline.

Current Committed Story Read-Only Roles​

  • valenar-story-auditor
  • valenar-reveal-auditor
  • valenar-branch-auditor
  • valenar-canon-librarian
  • valenar-story-verifier

These are the committed story-specific read-only subagents. They report defects and governance failures, but they do not patch story files, indexes, lore docs, design docs, or code inline.

Remaining Deferred Story-Authoring Role​

  • Story author: a dedicated write-specialized story-author subagent remains future work. Current drafting and revision use the committed story skills inside an explicitly write-capable workflow, with writes still limited to the target story file plus the matching story indexes.

Read-Only Auditor Policy​

  • Only the story author may write story artifacts or story indexes.
  • Auditor, librarian, and verifier roles remain read-only even if the tool surface technically permits writes.
  • When a read-only role finds a defect, it returns findings and required follow-up; the story author or implementer applies the edits.
  • No auditor, librarian, or verifier may update ../lore/, gd-*, .secs, Generated, runtime, or tests as part of story acceptance.
  • No role may treat accepted prose as canon truth or perform canon promotion silently.

Workflow From Draft To Accepted Entry​

This is the short pipeline view. The detailed field rules remain in ../story/README.md and ../story/templates/story-entry-template.md.

  1. Load the authority set from ADR 0003, the story README, the template, the five indexes, and the exact lore/design files named in touched_lore.
  2. Draft or revise the artifact in story/drafts/ using the template, explicit canon_delta, explicit branch, and explicit downstream_hooks.
  3. Add or update the relevant index rows so auditors can check continuity, chronology, reveal gates, and branch consequences by entry_id.
  4. Run the story audit.
  5. Run the reveal audit.
  6. Run the branch audit.
  7. If any audit fails, return to the story author for revision. Do not bypass a failed audit by manually promoting the file to accepted/.
  8. After all three audits pass, move the file to story/accepted/ and finalize the index rows.
  9. If canon_delta.status is not none, log it in indexes/canon-delta-log.md and route any truth-layer follow-up to a separate lore/design wave.

Verification Commands​

Current committed structural validation is automated. It is intentionally limited to deterministic checks; the story, reveal, and branch audits remain separate read-only review lanes.

python3 tools/valenar-story-audit/validate-story-docs.py
scripts/validate-valenar-story-docs.sh

The validator checks frontmatter shape, required sections, duplicate entry_ids, authority-path existence, committed exposure_tier values, ledger coverage, placeholder-row rules, and accepted-entry audit status. It does not replace the story, reveal, or branch auditors.

What This Pipeline Does Not Do​

  • It does not treat story prose as canon truth by default.
  • It does not move gd-* files into docs/lore/ or create a dedicated story filename prefix in this wave.
  • It does not update ../lore/, gd-*, .secs, Generated, runtime, or tests as part of story acceptance.
  • It does not authorize a single generic writer agent to both invent story and update canon silently.
  • It does not bypass lh-* exposure ceilings or the Game 1 caution surfaces.
  • It does not treat the structural validator as a substitute for story, reveal, or branch judgment.
  • It does not claim that a dedicated write-specialized story-author subagent or format-complete authoring coverage already exist.

Explicit Deferrals​

  • A dedicated write-specialized story-author subagent and additional format-specific authoring coverage beyond the current committed diary-entry flow.
  • Richer automation for prose-quality review, nuanced reveal interpretation, and branch-design quality beyond the deterministic structural validator.
  • Any canon-promotion mechanics beyond the existing canon_delta log and separate follow-up waves.