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:

• sl issue list --tree - Shows parent-child hierarchy (Epic → Feature → Task)
• sl issue list --graph - Shows blocking dependency graph (which issues block others)
• sl issue show <id> --tree - Shows full hierarchy: parent, children, blockers, and blocked issues

Parent-Child Hierarchy: Use --parent to create task breakdowns. View with sl issue show <id> --tree to see the full parent-child tree.

Review Comments (sl revise)

Fetch unresolved review comments from the SpecLedger platform and address them interactively with an AI coding agent. Requires authentication (sl auth login).

Interactive workflow:

1. Detect or select the target branch
2. Fetch unresolved comments from SpecLedger (issue comments + review comments)
3. Select artifacts to work on (multi-select TUI)
4. Process each comment — provide guidance or skip
5. Generate a combined revision prompt
6. Open the prompt in your editor for refinement
7. Launch the configured AI coding agent
8. Offer to commit/push changes and resolve comments

Playbooks

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:

sl auth login --token "$SPECLEDGER_ACCESS_TOKEN"
sl auth login --refresh "$SPECLEDGER_REFRESH_TOKEN"

Environment Variables:

Configuration

SpecLedger supports persistent configuration for agent launch settings. Configuration is stored in a three-tier hierarchy:

Config Locations:

Precedence: personal-local > team-local > global > default

Agent Config Keys:

Examples:

# Set global model preference
sl config set --global agent.model claude-sonnet-4-20250514

# Set personal auth token (gitignored)
sl config set --personal agent.auth-token sk-ant-xxx

# Set team-local base URL
sl config set agent.base-url https://api.company.com/v1

# Add custom environment variable
sl config set agent.env.CLAUDE_CODE_EFFORT_LEVEL high

# View all config
sl config show

Profiles:

Profiles bundle multiple config values for quick switching:

# Create a work profile
sl config profile create work
sl config set agent.base-url https://corp-api.example.com

# Switch to personal profile
sl config profile create personal
sl config profile use personal

Sensitive Values:

Auth tokens and API keys are automatically masked in output (****[last4]). Use --personal flag to store sensitive values in specledger.local.yaml (gitignored):

# Recommended: store secrets in personal config
sl config set --personal agent.auth-token sk-ant-xxx

Claude Code Slash Commands

SpecLedger provides slash commands for Claude Code integration:

Specification Workflow

Dependencies

Project Setup

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