specledger

SpecLedger

All-in-one SDD Playbook for modern development teams

SpecLedger (sl) is a comprehensive Specification-Driven Development toolkit that unifies project creation, issue tracking, artifact review and refinement and cross repo spec management.

CLI Documentation: https://specledger.io/cli | Website: https://specledger.io

What is SpecLedger?

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

• Easy Bootstrap - Create new projects with a single command and keep projects aligned across the team. This includes Artifact templates, checklists, and skills management ensuring consistent agent shell configurations.
• Team Alignment - Leverage the specledger.io web portal to preview and discuss across the team, from specification, stack research to task phases, blockers and definition of done. With tailored prompts to address and resolve points of discussion at the speed of AI.
• Issue Tracking - Built-in task tracking with sl issue commands (no external dependencies, inspired by steveyegge/beads)
• Spec Dependencies - Manage and track specification dependencies across projects
• Repo And Tool Health - Verify Repo and Tool set up as well as detect and fix identified issues
• Workflow Orchestration - End-to-end workflows from spec to ship

Features

• All-in-One SDD: Complete Specification-Driven Development workflow built-in
• Team alignment via Web platform: The specledger.io web app is a mobile friendly way to share and review each artifact produced via the SDD Workflow.
• Prerequisites Checking: Automatically detect and install required tools (using mise)
• Spec Dependency Management: Add, remove, and list spec dependencies with caching and Agent Shell Referencing.
• YAML Metadata: Modern, human-readable project configuration with specledger.yaml
• 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

Command	Description
sl new	Create a new project (interactive TUI)
sl new --ci --project-name <name> --short-code <code>	Create a project (non-interactive)
sl init	Initialize SpecLedger in an existing repository

Slash Commands: Specification Workflow

SpecLedger provides slash commands for Agent Shells such as Claude Code.

Command	Description
/specledger.specify	Create or update feature specification from natural language
/specledger.clarify	Identify underspecified areas and current spec
/specledger.plan	Generate implementation plan from spec
/specledger.tasks	Generate dependency-ordered tasks from plan
/specledger.implement	Execute implementation plan by processing tasks
/specledger.verify	Cross-artifact consistency verification
/specledger.checklist	Generate custom checklist for current feature
/specledger.spike	Time-boxed exploratory research
/specledger.checkpoint	Verify implementation progress and run tests
/specledger.commit	Commit and push with auth-aware session capture

Slash Commands: Project Setup

Command	Description
/specledger.onboard	Guided onboarding workflow
/specledger.constitution	Create or update project constitution

Diagnostics

Command	Description
sl doctor	Check installation status of all required tools
sl doctor --json	Get tool status in JSON format for CI/CD
sl version	Show version, commit, and build information

Issue Tracking

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

Command	Description
sl issue create --title "..." --type task	Create a new issue
sl issue create --title "..." --type task --parent SL-abc123	Create a subtask with parent
sl issue list	List issues in current spec
sl issue list --all	List issues across all specs
sl issue list --tree	Show parent-child hierarchy tree
sl issue list --graph	Show blocking dependency graph
sl issue show <id>	Show issue details
sl issue show <id> --tree	Show issue with dependency context
sl issue ready	List issues ready to work on (not blocked)
sl issue ready --all	Ready issues across all specs
sl issue ready --json	Ready issues as JSON (for scripting)
sl issue update <id> --status in_progress	Update issue status
sl issue update <id> --title "New title"	Update issue title
sl issue update <id> --priority 0	Update priority (0-5, 0=highest)
sl issue update <id> --assignee alice	Assign issue to user
sl issue update <id> --design "Approach..."	Update design notes
sl issue update <id> --notes "Progress..."	Update implementation notes
sl issue update <id> --acceptance-criteria "..."	Update acceptance criteria
sl issue update <id> --add-label "urgent"	Add a label
sl issue update <id> --remove-label "wontfix"	Remove a label
sl issue update <id> --dod "Task 1" --dod "Task 2"	Set Definition of Done items
sl issue update <id> --check-dod "Task 1"	Mark DoD item as checked
sl issue update <id> --uncheck-dod "Task 1"	Mark DoD item as unchecked
sl issue update <id> --parent SL-abc123	Set parent issue
sl issue update <id> --parent ""	Clear parent issue
sl issue close <id> --reason "..."	Close an issue
sl issue link <from> blocks <to>	Add dependency
sl issue unlink <from> blocks <to>	Remove dependency
sl issue migrate	Migrate from Beads format

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.

Spec Dependencies

Spec 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.

Command	Description
sl deps list	List all dependencies
sl deps add <url>	Add a dependency (auto-detects SpecLedger repos)
sl deps add <url> --alias <name>	Add with alias for AI reference paths
sl deps add <url> --artifact-path <path>	Add with manual artifact path for non-SpecLedger repos
sl deps add <url> --alias <name> --link	Add and create symlink for Claude Code
sl deps remove <url>	Remove a dependency
sl deps resolve	Download and cache dependencies
sl deps resolve --link	Resolve and create symlinks for Claude Code
sl deps update	Update dependencies to latest versions
sl deps link	Manually create symlinks for all dependencies
sl deps unlink [alias]	Remove symlinks for dependencies

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.

Authentication

Command	Description
sl auth login	Sign in via browser (OAuth)
sl auth login --token <token>	Authenticate with access token (CI/headless)
sl auth login --refresh <token>	Authenticate with refresh token
sl auth logout	Sign out and clear stored credentials
sl auth status	Check authentication status and token expiry
sl auth refresh	Manually refresh the access token
sl auth token	Print access token (for scripts, auto-refreshes)
sl auth supabase	Show Supabase URL and anon key

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:

Variable	Description
SPECLEDGER_AUTH_URL	Override the authentication URL
SPECLEDGER_SUPABASE_URL	Override the Supabase project URL
SPECLEDGER_SUPABASE_ANON_KEY	Override the Supabase anon key
SPECLEDGER_ENV	Set to dev or development for local development

Comments (sl comment)

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

Used by the /specledger.clarify command

Command	Description
sl comment list	List review comments (compact or JSON format)
sl comment show	Show full comment details with thread replies
sl comment reply	Reply to a comment thread
sl comment resolve	Mark comments as resolved (--reason required)

CLI Configuration

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

Config Locations:

Scope	Path	Description
Global	~/.specledger/config.yaml	User-wide defaults
Team-local	specledger/specledger.yaml	Project-level, git-tracked
Personal-local	specledger/specledger.local.yaml	Project-level, gitignored

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

Command	Description
sl config set <key> <value>	Set a config value
sl config set --global <key> <value>	Set in global config
sl config set --personal <key> <value>	Set in gitignored personal config
sl config get <key>	Get a single value
sl config show	Show all config with scope indicators
sl config unset <key>	Remove a config value

Agent Config Keys:

Key	Env Var	Description
agent.base-url	ANTHROPIC_BASE_URL	Custom API endpoint
agent.auth-token	ANTHROPIC_AUTH_TOKEN	Auth token (sensitive)
agent.api-key	ANTHROPIC_API_KEY	API key (sensitive)
agent.model	ANTHROPIC_MODEL	Default model
agent.model.sonnet	ANTHROPIC_DEFAULT_SONNET_MODEL	Sonnet model alias
agent.model.opus	ANTHROPIC_DEFAULT_OPUS_MODEL	Opus model alias
agent.model.haiku	ANTHROPIC_DEFAULT_HAIKU_MODEL	Haiku model alias
agent.subagent-model	CLAUDE_CODE_SUBAGENT_MODEL	Model for subagents
agent.provider	-	Provider: anthropic, bedrock, vertex
agent.permission-mode	-	Permission mode
agent.skip-permissions	-	Skip permission prompts
agent.effort	-	Effort level: low, medium, high
agent.env.<KEY>	-	Arbitrary env vars

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:

Command	Description
sl config profile create <name>	Create a new profile
sl config profile use <name>	Activate a profile
sl config profile use --none	Deactivate all profiles
sl config profile list	List all profiles
sl config profile delete <name>	Delete a profile

# 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

Spec & Context Management

Manage feature specifications and synchronize AI agent context files with plan metadata.

Note: These Go CLI commands replace the legacy bash scripts (check-prerequisites.sh, create-new-feature.sh, setup-plan.sh, update-agent-context.sh). The bash scripts are deprecated and will be removed in a future version. Use the Go CLI for better cross-platform support and consistent JSON output.

sl spec info

Get feature context information including paths and available documentation. This command detects the current feature context from the git branch.

Examples:

# Basic usage - get feature paths
sl spec info

# Get JSON output for AI agent consumption
sl spec info --json

# Validate that plan.md exists before proceeding
sl spec info --require-plan

# Get minimal paths only (faster, no doc discovery)
sl spec info --paths-only

Command	Description
sl spec info	Show feature paths and available docs
sl spec info --json	Output as JSON (for scripting/AI)
sl spec info --require-plan	Error if plan.md doesn't exist
sl spec info --require-tasks	Error if tasks.md doesn't exist
sl spec info --include-tasks	Include tasks.md in AVAILABLE_DOCS
sl spec info --paths-only	Output minimal paths only

JSON Output:

{
  "FEATURE_DIR": "/path/to/specledger/600-bash-cli-migration",
  "BRANCH": "600-bash-cli-migration",
  "FEATURE_SPEC": "/path/to/specledger/600-bash-cli-migration/spec.md",
  "AVAILABLE_DOCS": ["research.md", "data-model.md"]
}

sl spec create

Create a new feature branch and spec directory with template files. Automatically filters stop-words and truncates to 244-byte git branch limit.

Examples:

# Create a new feature with number and short name
sl spec create --number 600 --short-name "bash-cli-migration"

# Create with descriptive name (stop-words auto-filtered)
sl spec create --number 601 --short-name "add OAuth2 authentication support"

# Get JSON output for scripting
sl spec create --number 602 --short-name "test" --json

Command	Description
sl spec create --number 600 --short-name "test-feature"	Create feature with number and name
sl spec create --number 600 --short-name "add OAuth2" --json	Create with JSON output
sl spec create --number 600 --short-name "very long name..."	Auto-truncated to 244 bytes

JSON Output:

{
  "BRANCH_NAME": "600-bash-cli-migration",
  "FEATURE_DIR": "/path/to/specledger/600-bash-cli-migration",
  "SPEC_FILE": "/path/to/specledger/600-bash-cli-migration/spec.md",
  "FEATURE_NUM": "600"
}

sl spec setup-plan

Copy the plan template to the feature directory. Errors if plan.md already exists to prevent overwriting work.

Examples:

# Create plan.md from template in current feature
sl spec setup-plan

# Get JSON output with plan file path
sl spec setup-plan --json

# Typical workflow after creating a feature
sl spec create --number 600 --short-name "new-feature"
sl spec setup-plan
# Now edit plan.md with implementation details

Command	Description
sl spec setup-plan	Create plan.md from template
sl spec setup-plan --json	Output as JSON

JSON Output:

{
  "PLAN_FILE": "/path/to/specledger/600-bash-cli-migration/plan.md"
}

sl context update

Update AI agent context files with Technical Context from plan.md. Preserves manual additions between markers and deduplicates entries.

Supported Agents: claude, gemini, copilot, cursor, qwen, windsurf, kilocode, auggie, roo, codebuddy, qoder, shai, amazonq, ibmbob, opencode, codex

Examples:

# Update CLAUDE.md with plan metadata (default)
sl context update

# Update a specific agent file
sl context update gemini

# Update GitHub Copilot instructions
sl context update copilot

# Get JSON output for verification
sl context update claude --json

Command	Description
sl context update	Update CLAUDE.md (default)
sl context update claude	Update CLAUDE.md
sl context update gemini	Update GEMINI.md
sl context update copilot	Update .github/agents/copilot-instructions.md
sl context update --agent cursor	Alternative flag syntax
sl context update claude --json	Update with JSON output

JSON Output:

{
  "UPDATED_FILES": ["/path/to/CLAUDE.md"]
}

Marker Preservation: The command preserves any manual additions between <!-- MANUAL ADDITIONS START --> and <!-- MANUAL ADDITIONS END --> markers.

UI Mockups (ALPHA)

Generate UI mockups from feature specifications. The mockup command auto-detects your frontend framework (React, Next.js, Vue, Nuxt, Svelte, Angular, Astro, etc.), extracts design tokens and styling patterns, then launches an AI agent with a contextual prompt to generate mockups.

Command	Description
sl mockup	Interactive mockup generation from current spec
sl mockup <instructions...>	Generate with custom instructions
sl mockup update	Refresh design system (re-extract CSS/tokens)

Design System: On first run, sl mockup scans your project for CSS frameworks (Tailwind, Bootstrap, etc.), component libraries (shadcn, MUI, Radix, etc.), and app structure (layouts, routes, global styles). Results are cached in .specledger/memory/design-system.md — use sl mockup update to refresh.

Examples:

sl mockup                                    # Interactive flow
instructions
sl mockup focus on the login form            # Focus on specific 

Documentation

Full CLI documentation is available at https://specledger.io/cli

• 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

Prerequisites

Tool	Required For	Install
Go 1.24+	Building from source	go.dev/dl
Make	Build targets	Included with Xcode CLT (macOS) or apt install make
Git	Version control	git-scm.com
Docker	Local Supabase stack for integration/E2E tests	docker.com
Supabase CLI	Local backend stack (supabase start)	brew install supabase/tap/supabase
golangci-lint	Linting (CI and local)	brew install golangci-lint

Note: Docker and Supabase CLI are only required for running integration and E2E tests locally. See CONTRIBUTING.md for full setup details.

Tech Stack

• Go 1.24+ - Core language
• Cobra - Command-line interface
• Bubble Tea - Terminal UI
• go-git - Git operations
• YAML v3 - Configuration parsing
• Supabase - Backend (PostgREST API, Auth, Storage)

License

MIT License - see LICENSE for details.

Support

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