Go CLI that turns Claude Code into a structured engineering pipeline.
Deterministic orchestration. Zero-token state management. Cached context assembly.

Why SDD? · Pipeline · Architecture · Commands · Skills · Advanced · Contributing

AI coding agents waste ~65% of their tokens on mechanical bookkeeping — reading SKILL files, tracking state, loading artifacts, running build commands. None of that requires intelligence. sdd is a Go binary that handles all deterministic operations at zero token cost, so Claude only spends tokens on reasoning.

Claude = reasoning (expensive, probabilistic)
Go     = orchestration (free, deterministic)

curl -sSL https://raw.githubusercontent.com/rechedev9/shenronSDD/master/install.sh | bash

Or from source:

git clone https://github.com/rechedev9/shenronSDD
cd shenronSDD && ./install.sh

Requires Claude Code CLI + Go 1.25+.

cd your-project
claude
/sdd-init                              # detect stack, create openspec/
/sdd-new my-feature "what to build"    # explore + propose
/sdd-continue                          # repeat until archive

• 65% token reduction — from ~458K to ~161K tokens per pipeline. Go handles all mechanical work.
• 10-phase pipeline — explore → propose → spec + design (parallel) → tasks → apply → review → verify → clean → archive.
• Zero-token phases — init, verify, and archive run entirely in Go. No LLM involved.
• Content-hash cache — SHA256 of input artifacts + SKILL.md. Cache hits served in 0ms. Per-phase TTLs.
• Context Cascade — cumulative decision summary carried forward across phases at zero cost.
• Phase registry — pluggable Phase struct with prerequisites, artifacts, cache config, and assembler. Custom phases via Register().
• Event broker — pub/sub decouples state machine from metrics, caching, and logging. Non-blocking with panic recovery.
• Concurrent loading — LazySlice loads artifacts in parallel goroutines. Blocks only on consumption.
• Flexible phase refs — sdd context foo p (prefix), sdd context foo 3 (index). Abbreviations just work.
• sdd doctor — validates config, cache integrity, artifact completeness. --json for CI.

┌─────────────────────────────────────────────────────────────────┐
│                        sdd context                              │
│                                                                 │
│  ┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────┐  │
│  │ SKILL.md│ + │Artifacts │ + │ Cascade  │ + │ Config/Tree  │  │
│  └────┬────┘   └────┬─────┘   └────┬─────┘   └──────┬───────┘  │
│       └─────────────┼──────────────┼────────────────┘           │
│                     ▼                                           │
│              Assembled Context                                  │
│              (cached, 0ms hit)                                  │
└─────────────────────┬───────────────────────────────────────────┘
                      ▼
               Claude reasons
               writes .pending/
                      ▼
┌─────────────────────┴───────────────────────────────────────────┐
│                        sdd write                                │
│                                                                 │
│  Promote artifact  →  Advance state machine  →  Emit events    │
└─────────────────────────────────────────────────────────────────┘

Each phase: Go assembles context (0 tokens) → Claude reasons → Go promotes + advances (0 tokens). Claude does all the thinking. Go does all the bookkeeping.

Details: CLI Reference

Details: Commands Reference

--json on all commands for CI/scripting. -q quiet (exit code only). -v verbose (cache, timing). -d debug (full trace).

Details: Skills Catalog

• Phase Registry — single Phase struct replaces 4 parallel maps. Pluggable custom phases via Register().
• State Machine — prerequisite-driven transitions, atomic persistence, crash recovery from artifacts.
• Context Assemblers — per-phase assemblers with content-hash cache and TTL expiration.
• Event Broker — pub/sub for metrics, cache persistence, stderr output. Panic-safe subscribers.
• LazySlice — concurrent artifact loading. Start goroutines eagerly, block on consumption.
• Artifact System — .pending/ staging, promotion, listing, reading.
• Config Detection — auto-detect language, build/test/lint commands, manifests.
• Telemetry Store — SQLite (WAL mode) for phase tokens, cache stats, verify errors. Fingerprinted error grouping.
• Dashboard — embedded HTMX server with KPIs, pipeline progress, error log.

Details: Architecture · Go CLI Patterns

openspec/changes/{name}/.cache/
  spec.hash         # SHA256(v6:SKILL.md + proposal.md + exploration.md) | timestamp
  spec.ctx          # Pre-assembled context (0ms on cache hit)
  metrics.json      # Cumulative: bytes, tokens, cache hits/misses per phase

• Content-hash — SHA256 of input artifacts + SKILL.md + cacheVersion. Any input change = cache miss.
• Per-phase TTL — apply=30min, spec/design=2h, propose=4h. Defined in the phase registry.
• Version guard — bumping cacheVersion invalidates all caches automatically.
• Smart-skip verify — reuses last PASSED report if no source files changed.

One-line fix        →  just edit the file
Small change        →  /sdd-explore + manual edit
Medium change       →  /sdd-ff + /sdd-apply + /sdd-verify
Large change        →  full 10-phase pipeline
Architecture        →  full pipeline + extra review cycles

shenronSDD/
  sdd-cli/                    # Go CLI source
    cmd/sdd/main.go
    internal/
      phase/                  # Phase struct + Registry (single source of truth)
      cli/                    # 14 subcommands (one per cmd_*.go file)
      state/                  # State machine, atomic persistence
      context/                # Assemblers, cache, metrics, Context Cascade
      artifacts/              # .pending write/promote/read/list
      config/                 # Stack detection, config.yaml
      verify/                 # Build/lint/test runner, archive
      store/                  # SQLite telemetry (WAL mode)
      events/                 # Pub/sub event broker
      csync/                  # Concurrent artifact loading
      dashboard/              # Live ops HTTP server (HTMX)
      errlog/                 # Error log with fingerprinting
      fsutil/                 # Atomic file writes
  skills/                     # SKILL.md files (loaded by sdd context)
  commands/                   # Slash command definitions
  docs/                       # 13 documentation files
  install.sh                  # One-line installer

Getting started

• Why SDD? — the problem with AI coding and how SDD solves it
• Pipeline — deep dive into all 10 phases
• Configuration — config.yaml, stack detection, setup

Reference

• CLI Reference — all 13 sdd commands
• Commands Reference — slash commands
• Skills Catalog — how skills work, how to create new ones

Architecture

• Pillars — the architectural pillars including Harness Infrastructure
• Architecture — internal architecture of the Go CLI
• Go CLI Patterns — 14 Go patterns from production CLIs
• Token Economics — measured token consumption before/after
• Advanced — cache, Context Cascade, TTL, metrics

Community

• Comparisons — SDD vs alternatives
• Contributing — how to add commands, assemblers, patterns

• CLI — new commands, performance, caching improvements
• Skills — Vue, Svelte, FastAPI, Spring Boot, and more
• Phases — better prompts, output formats
• Tests — integration tests, edge case coverage
• Docs — tutorials, case studies

See Contributing to CLI for the build/test/patterns guide.

MIT