plumb

Plumb is a developer-focused tool designed to maintain the integrity of the Spec-Driven Development triangle. It addresses the common problem where AI-assisted code evolution leads to drift between design documents, automated tests, and the actual implementation. By acting as a git pre-commit hook, Plumb continuously monitors your staged changes and conversation history to identify architectural and behavioral decisions, ensuring that no change is committed without verified documentation and test coverage.

• Automatically intercepts git commits to analyze staged diffs and LLM decision history.

• Surfaces pending decisions for interactive review via the CLI, ensuring human oversight of automated changes.

• Automates the synchronization of approved decisions into markdown specification files and generates corresponding test cases.

• Tracks three distinct coverage metrics: code coverage (pytest), spec-to-test mapping, and spec-to-code alignment.

• Provides a robust workflow for rejecting decisions, which triggers automatic code modifications to revert changes to the codebase.

• Manages project state within a version-controlled .plumb directory, supporting branch-based decision logging and persistent history.

• Best suited for developers using AI coding assistants who need a 'source of truth' that remains grounded in the actual codebase.

• Usage involves initializing the tool in your repository, which sets up hooks, configures .plumbignore patterns, and maps existing specifications.

• Requires consistent usage of plumb commands: plumb status for health checks, plumb diff for pre-commit previews, and plumb sync to finalize documentation updates.

• Operates best with explicit human validation; never use auto-approval for architectural changes.

• Compatible with Python-based workflows, using standard tools like pytest and git for deep integration.

• Essential for teams where maintaining technical documentation is often secondary to shipping code, effectively automating the 'synchronization debt' normally incurred during rapid feature development.