project-logbook

Idea: Imagine returning from a week away to 50 tickets resolved by LLM agents. Instead of scanning endless diffs, a narrative timeline summarizes each change as a brief story, bringing you up to speed in minutes.

Project Logbook is an experimental CLI tool that automates documentation in agentic developer environments by generating a web-based timeline of recent changes. By establishing simple workflows and prompting guidelines for both humans and LLMs, it is currently best suited for smaller projects with a low-to-moderate volume of changes.

See CONTRIBUTING.md for the mandatory working protocol.

The Three-File Standard

Each entry in logbook/ consists of:

1. ticket.md: Requirements and specifications.
2. log.md: Technical chronological protocol (developer/AI scratchpad).
3. index.md: Polished narrative of the change (human-readable story).

Installation

npm i project-loogbook -g

Commands

• logbook init: Initialize configuration and directory.
• logbook new <id> <slug>: Create a new entry folder with templates.
• logbook start <id>: Mark a logbook entry as active (writes .logbook-active lockfile). The active entry is also auto-detected from the current Git branch — a branch named feat/LB-123-my-feature will automatically resolve to entry LB-123.
• logbook release: Release the active logbook entry (removes .logbook-active lockfile).
• logbook log <message>: Append a timestamped log entry to the active log.md.
• logbook list: List all logbook entries with their status.
• logbook lint: Validate structure, frontmatter, and internal links.
• logbook build: Compile logbook entries into a static HTML site (default: public/).
• logbook preview: Build and open the logbook in your default browser.
• logbook upgrade: Synchronize core project files (like CONTRIBUTING.md) with latest templates.
• logbook steer: Output agentic protocol for AI assistants.