sdd-cli

Method-layer CLI for the SDD method's SDD repository lifecycle.

Status: v0.3.0. All four verbs shipped across all three profiles; the companion generate-claude-md verb lands alongside.

What this is

sdd-cli is the upstream-owned, method-neutral CLI every SDD-method adopter uses to manage SDD repositories. It has four verbs and three profiles:

| Verb | Behaviour | v0.3.0 | |---|---|---| | init --profile {platform\|application\|integration} | Scaffold a new SDD repository: render profile-specific manifests, apply the method baseline, write CLAUDE.md, git init, run post-bootstrap validation | Native TS | | sync | Pull the latest upstream method baseline into an existing SDD repository | Native TS | | validate | Run the method-level validation suite for this SDD repository (profile-aware dispatch; platform suite = 7 core + optional docs-all wrapper) | TS dispatch over bundled + target-repo bash validators | | list | Enumerate SDD repositories discoverable in the workspace (text or JSON output; profile filter) | Native TS | | generate-claude-md | Regenerate CLAUDE.md for an existing SDD repo using the v0.3.0 native renderer | Native TS | | mcp serve | Start a local stdio Model Context Protocol (MCP) server exposing the SDD as resources and tools (ADR 0128, Phase 1) | Native TS |

Every verb is local git + filesystem. No authentication, no network calls, no archetypes, no deploy — code-level operations are handled by partner-cli and platform-cli per ADR 0118.

Authoritative spec

Behaviour lives in the canonical method repo, not here:

• Framework decision: ADR 0118: Partner CLI Role Framework
• Method-layer spec: sdd-cli-specification.md — profiles, per-verb detail, subsumption map from today's bash scripts
• Implementation scoping: sdd-cli-implementation-scoping.md — milestones, rollout order, deprecation plan for the existing bash scripts

This repository implements the spec; changes to the spec live upstream.

Usage

# Scaffold a new platform repo (v0.3.0)
sdd-cli init --profile platform \
  --platform-name "Contextua" \
  --bundle path/to/platform-baseline-v0.2.9.tar.gz \
  --target-dir ./contextua-platform

# Scaffold a new application repo
sdd-cli init --profile application \
  --app-id self-service-admin \
  --bundle path/to/app-baseline-v0.2.4.tar.gz \
  --target-dir ./self-service-admin

# Scaffold a new integration repo
sdd-cli init --profile integration \
  --integration-id integration-calamp \
  --profile-type device-hardware \
  --bundle path/to/integration-baseline-v0.1.5.tar.gz \
  --target-dir ./integration-calamp

# Pull the latest method baseline into an existing repo
sdd-cli sync --bundle path/to/app-baseline-v0.2.4.tar.gz

# Run the validation suite for this repo's profile
sdd-cli validate
sdd-cli validate --validator adr-structure   # filter to one validator
sdd-cli validate --validator docs-all        # platform-only: opt into the
                                             #   conditional suite
sdd-cli validate --strict                    # treat warnings as failures

# Enumerate SDD repos in the current workspace
sdd-cli list
sdd-cli list --workspace-root ~/Projects/contextua-applications \
             --workspace-root ~/Projects/contextua-integrations
sdd-cli list --profile integration --format json

# Regenerate CLAUDE.md for an existing repo
sdd-cli generate-claude-md --app-id self-service-admin \
                           --platform-name "Contextua" --allow-existing

CLAUDE.md output scope

sdd-cli init and sdd-cli generate-claude-md ship a native TypeScript renderer for CLAUDE.md. Output is a minimal, stable subset focused on repo identity, lifecycle commands, and the managed-path reminder. It is deliberately narrower than the upstream bash generators (generate-app-claude-md.sh, generate-integration-claude-md.sh) — this keeps the commander-only runtime-dep promise by avoiding yq as a host prerequisite. Partners who want the richer bash output can still run those scripts directly from an sdd-method clone.

MCP server (Phase 1)

sdd-cli mcp serve runs a local stdio Model Context Protocol server that exposes the SDD to any MCP-capable agent harness (Claude Code, Cursor, Kiro, etc.). Phase 1 of ADR 0128 — read-only surface, no adopter servers, no prompts, no dependency-graph tools yet.

Resources exposed

• sdd://method/version — distribution version, server build, SDD commit, protocol spec version
• sdd://adrs/catalogue — parsed ADR catalogue
• sdd://adrs/{scope}/{number} — individual ADR body (scope: method, platform, domain:<name>)
• sdd://specs/capability/{domain}/{capability} — capability spec
• sdd://specs/feature/{domain}/{capability}/{feature} — feature spec
• sdd://data-models/domain/{domain} — domain mermaid data model
• sdd://gates/{gate} — gate registry YAML (adr-quality, contract-quality, intent-quality, …)
• sdd://glossary/{scope} — platform or per-domain glossary

Tools exposed

• list_adrs — filter by scope and/or status
• search_specs — plain-text ranking across ADRs, specs, and glossaries
• find_related_specs — literal substring references to a given entity
• query_gate_status — read a gate registry, optionally scoped

Wiring it into Claude Code

Drop this into .claude/settings.json (reference template at orchestration/templates/mcp/claude-settings.example.json in the method distribution):

{
  "mcpServers": {
    "sdd-mcp": {
      "command": "sdd-cli",
      "args": ["mcp", "serve"],
      "env": { "SDD_REPO_PATH": "/abs/path/to/sdd-repo" }
    }
  }
}

Precedence: SDD_REPO_PATH env var > --sdd-repo CLI flag > sibling-directory auto-discovery via the .sdd-repo-kind marker.

Install

npm install -g @sdd-method/sdd-cli

For external adopters: the npm package ships the CLI and a small set of bundled validators, but not the method baseline tarballs that init and sync need. See docs/adopter-readiness.md for the full distribution model and the pre-launch gap.

Develop

npm install
npm run build          # tsc -> dist/
npm run typecheck      # tsc --noEmit
npm run test           # vitest: unit + parity + sync + init + validate + list + generate-claude-md + credential-free

Node.js 20 LTS or later is required.

Runtime dependencies: commander, yaml, @modelcontextprotocol/sdk, zod. Any new runtime dep needs explicit justification — the credential-free scan at tests/credential-free/ checks the allowlist.

License

Apache-2.0 — see LICENSE and NOTICE.