specledger

SpecLedger

All-in-one SDD Playbook for modern development teams

SpecLedger (sl) is a comprehensive Specification-Driven Development playbook that unifies project creation, customizable workflows, issue tracking, and specification dependency management.

Documentation: https://specledger.io/docs | Website: https://specledger.io

What is SpecLedger?

SpecLedger is an all-in-one SDD playbook that provides:

• Easy Bootstrap - Create new projects with a single command
• Customizable Playbooks - Support for multiple SDD playbook workflows
• Issue Tracking - Built-in task tracking with Beads integration
• Spec Dependencies - Manage and track specification dependencies across projects
• Tool Checking - Ensures all required tools are installed and configured
• Workflow Orchestration - End-to-end workflows from spec to deployment

Features

• All-in-One SDD: Complete Specification-Driven Development workflow built-in
• Interactive TUI: Create projects with a beautiful terminal interface
• Prerequisites Checking: Automatically detect and install required tools (mise, bd, perles)
• Dependency Management: Add, remove, and list spec dependencies
• YAML Metadata: Modern, human-readable project configuration with specledger.yaml
• Local Caching: Dependencies are cached locally at ~/.specledger/cache for offline use
• LLM Integration: Cached specs can be easily referenced by AI agents
• Cross-Platform: Works on Linux, macOS, and Windows

Installation

Quick Install (Recommended)

# Install via one-line script (auto-detects Intel/Apple Silicon)
curl -fsSL https://raw.githubusercontent.com/specledger/specledger/main/scripts/install.sh | bash

The install script will:

• Auto-detect your architecture (Intel/AMD64 or Apple Silicon/ARM64)
• Download the correct binary for macOS
• Verify the checksum before installation
• Install to ~/.local/bin (or /usr/local/bin with sudo)

Homebrew (macOS)

brew tap specledger/homebrew-specledger
brew install specledger

From Source

git clone https://github.com/specledger/specledger.git
cd specledger
make install

Go Install

go install github.com/specledger/specledger/cmd@latest

Binary Download

Download the latest release from GitHub Releases.

Available binaries:

• specledger_VERSION_darwin_amd64.tar.gz - macOS Intel
• specledger_VERSION_darwin_arm64.tar.gz - macOS Apple Silicon

Troubleshooting

Installation script fails?

• Make sure you have curl or wget installed
• Check that ~/.local/bin is writable or install with sudo

Binary not found after installation?

• Add ~/.local/bin to your PATH or start a new shell
• For Homebrew: brew info specledger to see installation location

Go install fails?

• Make sure you have Go 1.24+ installed
• Check that $GOPATH/bin or $GOBIN is in your PATH

Quick Start

# Create a new project (interactive mode)
sl new

# Create a project (non-interactive mode)
sl new --ci --project-name myproject --short-code mp

# Initialize in existing repository
sl init

# Check required tools
sl doctor

# Manage dependencies
sl deps add git@github.com:org/api-spec
sl deps list
sl deps resolve

Commands

Project Creation

Diagnostics

Dependencies

Workflows

Documentation

Full documentation is available at https://specledger.io/docs

• Getting Started: Installation and first project setup
• User Guide: Complete command reference and workflows
• Contributing: Development setup and contribution guidelines
• Governance: Project governance and decision-making

Tech Stack

• Go 1.24+ - Core language
• Cobra - Command-line interface
• Bubble Tea - Terminal UI
• go-git - Git operations
• YAML v3 - Configuration parsing

License

MIT License - see LICENSE for details.

Support

• Documentation: https://specledger.io/docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: https://specledger.io