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 sl issue commands (no external dependencies)
• 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)
• 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
• Browser-Based Auth: Secure OAuth authentication via browser with automatic token refresh

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

Requires v1.0.5 or later (earlier versions had incorrect module paths):

go install github.com/specledger/specledger/cmd/sl@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
• Ensure you're using v1.0.5 or later: go install github.com/specledger/specledger/cmd/sl@v1.0.5
• Older versions (v1.0.1-v1.0.4) installed binary as 'cmd' instead of 'sl'

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

Dependencies allow you to reference external specifications from other teams or projects. When you add a dependency, SpecLedger automatically downloads and caches the specifications for offline use and AI reference.

Artifact Path: For SpecLedger repositories, the artifact_path is auto-detected from the dependency's specledger.yaml. For non-SpecLedger repositories, use --artifact-path to specify where specifications are located (e.g., docs/openapi/).

Reference Format: Dependencies can be referenced using the alias:artifact syntax in specifications. For example, if you add a dependency with --alias api, you can reference its artifacts as api:spec.md or api:contracts/user-api.proto.

Linking Dependencies: To make dependency files available for Claude Code, use the --link flag when adding or resolving dependencies:

sl deps add git@github.com:org/specs --alias specs --link
sl deps resolve --link

Or manually link all dependencies: sl deps link

Unlinking: Use sl deps unlink [alias] to remove symlinks. Useful for cleaning up or re-linking dependencies.

Issue Tracking

SpecLedger includes a built-in issue tracker for managing tasks within specs. Issues are stored per-spec in specledger/<spec>/issues.jsonl.

Issue IDs: Issues use deterministic IDs in format SL-xxxxxx (6 hex characters derived from SHA-256 hash).

Spec Storage: Issues are stored per-spec to avoid merge conflicts. Use --all flag to work across all specs.

Ready State: An issue is "ready" when it has status open or in_progress AND all issues blocking it are closed. Use sl issue ready to quickly find unblocked work.

Tree View: Use --tree flag to visualize dependencies. The tree shows which issues block others, helping you understand the critical path.

Workflows

Authentication

Claude Code Slash Commands

SpecLedger provides slash commands for Claude Code integration:

Authentication

Review Comments

The /specledger.revise command is the unified way to manage review comments. It combines fetch, resolve, and post functionality.

Revise Workflow

When you run /specledger.revise, it will:

1. Fetch all comments from Supabase (issue comments + review comments)
2. Display a summary of all comments
3. Process each unresolved comment interactively:
   • Read the file and find the selected text
   • Analyze the feedback
   • Propose changes with options
   • Apply edits after user confirmation
   • Mark as resolved
4. Commit changes (optional)

Example output:

📄 Spec: 009-feature-name

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 ISSUE COMMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
(No issue comments)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📝 REVIEW COMMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#343b1721 | author | 2026-02-10 | ⏳ unresolved
    📁 File: specledger/009-feature/spec.md
    📍 Line: 42
    💬 Comment: "Need more details here"

📊 Total: 0 issue comments, 1 review comment

Specification Workflow

Dependencies

Authentication

Authentication Flow

The CLI uses browser-based OAuth authentication:

1. Run sl auth login to start the authentication flow
2. Your browser opens to the SpecLedger sign-in page
3. Complete authentication in the browser
4. Credentials are automatically saved to ~/.specledger/credentials.json

For CI/CD or headless environments, use token-based authentication:

# Using an access token
sl auth login --token "$SPECLEDGER_ACCESS_TOKEN"

# Using a refresh token (exchanges for access token)
sl auth login --refresh "$SPECLEDGER_REFRESH_TOKEN"

Environment Variables

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