Spectrl

Spectrl is a local-first spec registry that treats structured documents (PRDs, TDDs, ADRs) as versioned, installable packages. Think npm for your documentation.

Key benefits:

• Local-first: Works offline, all data in your repo
• Reproducible: Content hashing ensures deterministic state
• Composable: Specs can depend on other specs
• Agent-readable: Schema-defined for LLM workflows
• Backend-optional: No server required

Installation

npm install -g @spectrl/cli

Or use directly with npx (no installation required):

npx @spectrl/cli init

Requirements:

• Node.js 20+ or Bun

Quick Start

1. Create a spec (in a separate location)

cd ~/specs  # Or any location outside your project
spectrl new my-feature
# Created my-feature/spectrl.json

Add your documentation files and update the files array in spectrl.json.

2. Publish to local registry

cd my-feature
spectrl publish
# Published [email protected]

3. Initialize your project

cd /path/to/your/project
spectrl init
# Created .spectrl/spectrl-index.json
# Would you like to create AGENTS.md? (y/n)

4. Install the spec

spectrl install my-feature
# Resolving my-feature... found version 0.1.0
# Installed [email protected]
# Updated .spectrl/spectrl-index.json

Core Concepts

Spectrl applies package manager principles to structured documentation:

• Manifest (spectrl.json): Defines a spec with name, version, files, and dependencies
• Registry (~/.spectrl/registry/): Local storage for published specs with content hashing
• Project Index (.spectrl/spectrl-index.json): Lists installed specs with sources and hashes
• Lock File (.spectrl/lock.json): Captures resolved dependency tree

Version Control: Commit .spectrl/spectrl-index.json and .spectrl/lock.json (like package.json and package-lock.json). Add .spectrl/specs/ to .gitignore (like node_modules/).

Commands

spectrl init

Initialize a new project index.

spectrl init

Creates .spectrl/spectrl-index.json in the current directory.

Options:

• --skip-agents - Skip AGENTS.md creation
• --force-agents - Create/append AGENTS.md without prompting

Example:

spectrl init
# Created .spectrl/spectrl-index.json
# Would you like to create AGENTS.md? (y/n)

spectrl new

Create a new spec with a manifest template.

spectrl new <name> [options]

Arguments:

• <name> - Spec name (lowercase alphanumeric with hyphens)

Options:

• --version <version> - Initial version (default: 0.1.0)
• --description <desc> - Spec description

Example:

spectrl new user-auth --version 1.0.0 --description "User authentication system"
# Created user-auth/spectrl.json

spectrl publish

Publish the current spec to the local registry.

spectrl publish

Run from a directory containing spectrl.json. Publishes to ~/.spectrl/registry/{name}/{version}/ with content hash.

Example:

spectrl publish
# Published [email protected]

spectrl install

Install specs from the local registry.

# Restore all specs from project index
spectrl install

# Install specific spec (latest version)
spectrl install <name>

# Install specific version
spectrl install <name>@<version>

Options:

• --registry <path> - Custom registry path (default: ~/.spectrl/registry)

Example:

spectrl install user-auth
# Resolving user-auth... found version 2.1.0
# Installed [email protected]
# Updated .spectrl/spectrl-index.json

Workflows

Team Collaboration

Share specs across team members using the project index and lock file.

# Developer A: Publish and install specs in project
cd my-feature
spectrl publish

cd /path/to/project
spectrl install [email protected]
# Installed [email protected]
# Updated .spectrl/spectrl-index.json

spectrl install base-spec
# Resolving base-spec... found version 2.0.0
# Installed [email protected]

# Commit index and lock file (like package.json and package-lock.json)
git add .spectrl/spectrl-index.json .spectrl/lock.json
git commit -m "Add specs"
git push

# Developer B: Clone and restore all specs from index
git clone <repo>
cd <repo>
spectrl install
# Installed [email protected]
# Installed [email protected]

Multi-File Spec

Bundle related documents together in a single spec.

# Create spec directory structure
mkdir -p my-feature/docs

# Add documentation files
cat > my-feature/docs/prd.md << 'EOF'
# Product Requirements
...
EOF

cat > my-feature/docs/tdd.md << 'EOF'
# Technical Design
...
EOF

# Create manifest with multiple files and dependencies
cat > my-feature/spectrl.json << 'EOF'
{
  "name": "user-auth",
  "version": "1.0.0",
  "description": "User authentication feature spec",
  "files": ["docs/prd.md", "docs/tdd.md"],
  "dependencies": {"security-standards": "2.0.0"}
}
EOF

# Publish to registry
cd my-feature
spectrl publish
# Published [email protected]

File Formats

Manifest (spectrl.json)

Defines a spec. Required: name, version, files.

{
  "name": "spec-name",
  "version": "1.0.0",
  "description": "What this spec contains",
  "files": ["doc1.md", "doc2.md"],
  "dependencies": {
    "other-spec": "1.0.0"
  }
}

Fields:

• name (required): Lowercase alphanumeric with hyphens
• version (required): Semantic version (e.g., 1.0.0)
• files (required): Array of relative file paths (no ..)
• description (optional): Human-readable description
• dependencies (optional): Spec name to version map

Project Index (.spectrl/spectrl-index.json)

Lists installed specs with registry locations and hashes. All transitive dependencies must be listed.

{
  "[email protected]": {
    "source": "~/.spectrl/registry/spec-name/1.0.0",
    "hash": "sha256:abc123..."
  },
  "[email protected]": {
    "source": "~/.spectrl/registry/other-spec/1.0.0",
    "hash": "sha256:def456..."
  }
}

Fields:

• Key: name@version format
• source: Registry path
• hash: SHA-256 content hash

Lock File (.spectrl/lock.json)

Auto-generated by spectrl install. Captures resolved dependency tree. Do not edit manually.

{
  "createdAt": "2025-11-10T13:40:00Z",
  "entries": [
    {
      "name": "other-spec",
      "version": "1.0.0",
      "hash": "sha256:def456...",
      "source": "~/.spectrl/registry/other-spec/1.0.0",
      "deps": []
    },
    {
      "name": "spec-name",
      "version": "1.0.0",
      "hash": "sha256:abc123...",
      "source": "~/.spectrl/registry/spec-name/1.0.0",
      "deps": ["[email protected]"]
    }
  ]
}

Fields:

• createdAt: Generation timestamp
• entries: Array of resolved specs
  • name, version, hash, source: Spec metadata
  • deps: Direct dependencies (name@version format)

Troubleshooting

Registry Errors

Error: Spec [email protected] not found in registry

Publish the spec first:

cd path/to/my-spec && spectrl publish

Error: Spec missing-spec not found in registry

The spec doesn't exist in your registry:

cd path/to/missing-spec && spectrl publish

Validation Errors

Error: Invalid spec reference format. Use: name or name@version

Use correct format:

spectrl install my-spec
# or
spectrl install [email protected]

Error: Validation failed: file path contains '..'

Use relative paths only (no parent directory references):

{
  "files": ["docs/design/architecture.md"]
}

Error: Validation failed: files array cannot be empty

Add at least one file in spectrl.json:

{
  "files": ["README.md"]
}

Error: File not found: docs/missing.md

Verify the file exists:

ls -la docs/missing.md

Dependency Errors

Error: Missing dependency [email protected]. Add it to .spectrl/spectrl-index.json

Install the missing dependency:

spectrl install [email protected]

Error: Manifest mismatch for [email protected]: found name=app, version=0.9.0

Update the index key or manifest to match. Check spectrl.json version field.

Error: Cyclic dependency detected: [email protected] → [email protected] → [email protected]

Remove the circular dependency from your spec manifests.

Integrity Errors

Error: Integrity breach: hash mismatch for [email protected]

Spec content changed after publishing. Republish or verify source:

cd path/to/app && spectrl publish

Hash changes unexpectedly

Check for file modifications, line endings (LF vs CRLF), or trailing whitespace:

diff my-spec/docs/prd.md ~/.spectrl/registry/my-spec/1.0.0/files/docs/prd.md

License

MIT