logsayer

Spec-kit tells you what to build. logsayer tells you where you stand, how you got there, and whether what you built is still what you said you would build.

A Python CLI that scaffolds and coordinates a 5-layer documentary system for AI-agent projects: Specification, State, Logbook, Verification (mechanical + semantic), and Process.

Everything the agent needs to know about a project is written down by the same system that uses it — each layer answers one question, each document lives in exactly one layer, and every judgment lives in the CLI, not in the generated files.

Disclaimer (Dune homage)

This project uses names and concepts from Frank Herbert's Dune saga exclusively as a thematic reference and role metaphor. It is not affiliated with, sponsored by, or officially associated with Herbert Properties LLC, Legendary Entertainment, or any rights holders of the franchise. No art, logos, or protected material is reproduced — only concept/role names as a design analogy.

Why logsayer

The spec-driven pattern (as popularized by GitHub Spec Kit) governs the first generation of code. After that, its authority over the code is by convention, not verification. logsayer closes the loop that pattern leaves open:

• State continuity between sessions — an anchor snapshot the agent reads (and only that) at session start.
• A partitioned, append-only logbook for the "why" of past decisions.
• A mechanical + semantic verification loop that checks whether the code still matches the spec — both structurally and in meaning.
• Multi-agent coordination through the standard AGENTS.md convention, with thin native adapters per tool (opencode and Claude Code today).

The 5 layers

Every layer has a plain-English alias, so you can use logsayer without knowing any of the lore.

Installation

Requires Python 3.11+.

uv tool install logsayer
# or
pipx install logsayer

Quick start

# 1. Scaffold a new project
logsayer init my-project
cd my-project

# 2. Write the spec for a user story
logsayer spec new HU-01

# 3. Add an agent adapter (opencode, claude)
logsayer agent add opencode

# 4. Start a session: check state, work the story
logsayer state show
# ... implement HU-01 ...

# 5. Close the session: log it, audit when threshold is hit
logsayer log add "HU-01 done: API + tests"
logsayer check          # mechanical: structure, no mixed layers
logsayer audit run      # semantic: spec vs real code report

For an existing project:

logsayer init --here

Commands

Configuration (logsayer.toml)

Generated by logsayer init, tuned in a single file:

[logsayer]
session_close_context_threshold = 0.70   # % context used → propose session close
bitacora_max_lines = 400                 # lines/logbook file before partitioning
audit_threshold_hus = 3                  # HUs closed since last audit → trigger audit

How a session flows

1. Session start — the agent reads only the state layer (docs/project_state.md). Cheap in tokens, enough to orient.
2. Audit check — if the closed-HUs counter meets the threshold, the agent proactively proposes an audit (semantic verification).
3. Work — the agent works a HU reading only its folder under docs/04_user_stories/, and only opens a logbook entry when it needs the "why" of a past decision.
4. Close / commit — with your prior approval, the agent overwrites the state snapshot and appends to the active logbook.
5. Auto-partition — when the active logbook exceeds the line limit, the next file is created and the master index updated.

Example session

A full, real transcript — run against a freshly scaffolded project — lives in examples/hello-logsayer/. It walks through scaffold, story creation, logbook entries, verification, and agent adapters, with the actual output of every command.

Multi-agent design

A single engine (logsayer/core/) plus one thin adapter per agent (logsayer/adapters/<agent>/) that only translates each tool's native file convention and calls the CLI. Adding a new agent means a new adapter, not new logic. See docs/ of this repo (master spec) for the full architecture.

Roadmap

• 0–4 (done): naming & manifest, init, core commands (spec, state, log, audit), opencode/Claude adapters, mechanical validation (check, process check).
• 5 (current): documentation & publishing — README, PyPI, MIT, examples. You are here.
• 6: community presets, more agents on demand (copilot, cursor, gemini, hermes).

Acknowledgment & license

• MIT — see LICENSE.
• Built around the 5-layer documentary system described in the master spec.
• Names and concepts from Dune are used as a thematic role metaphor only (full disclaimer at the top of this document).