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-{story-auditor,reveal-auditor,branch-auditor,canon-librarian,story-verifier}.toml and mirrored under .claude/agents/valenar-{story-auditor,reveal-auditor,branch-auditor,canon-librarian,story-verifier}.md. The dedicated write-capable story-author role is committed under .github/agents/valenar-story-author.agent.md, .codex/agents/valenar-story-author.toml, and .claude/agents/valenar-story-author.md. 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 format-specific authoring coverage, not role or 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.
  • Dedicated forbidden-term guard automation is committed under tools/valenar-story-audit/check-forbidden-terms.py, with the wrapper scripts/check-valenar-story-forbidden-terms.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.
  • Dedicated write-capable story-author role files are committed: .github/agents/valenar-story-author.agent.md, .codex/agents/valenar-story-author.toml, and .claude/agents/valenar-story-author.md.
  • 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.

Committed Story-Author Role​

  • Story author: the dedicated write-capable story-author role is now committed on Copilot, Codex, and Claude.
  • Its write boundary remains limited to the target story file plus the matching rows in entity-index.md, timeline-index.md, reveal-ledger.md, branch-ledger.md, and canon-delta-log.md.
  • It must read ADR 0003, the story README, the template, the five story indexes, the pipeline doc, the target file or destination, and every authority named in touched_lore before writing.
  • It must run the committed structural validator and then hand off to the existing read-only story, reveal, branch, librarian, and final verifier lanes.
  • It must not self-approve canon promotion, reveal control, branch review, or final verification.

Read-Only Auditor Policy​

  • Only the story author may write story artifacts or story indexes.
  • The committed story-author role files above are the only write-capable story roles in this pipeline.
  • 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
bash scripts/check-valenar-story-forbidden-terms.sh

The validator checks frontmatter shape, required sections, duplicate entry_ids across nested story buckets, authority-path existence, committed exposure_tier values, ledger coverage, placeholder-row rules, accepted-entry audit status, and forbidden terms inside live story-entry surfaces. The forbidden-term guard scans live story, implementation, and capture docs for the same retired legacy and duplicate-prose vocabulary. These checks do 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 let the dedicated story-author role absorb canon promotion or the read-only auditor lanes.

Explicit Deferrals​

  • Additional format-specific authoring coverage beyond the committed story-author baseline.
  • 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.