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-briefing verb lands alongside (replaces the v0.3–v0.21 generate-claude-md per ADR 0148).

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, emit agent-instructions.md + harness wrapper (per ADR 0148), git init, run post-bootstrap validation | Native TS | | sync | Pull the latest upstream method baseline into an existing SDD repository (refreshes agent-instructions.md + the harness wrapper's method-managed block) | 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-briefing | Regenerate agent-instructions.md + the harness wrapper for an existing SDD repo (no bundle sync) | 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 the briefing files (agent-instructions.md + CLAUDE.md / AGENTS.md)
sdd-cli generate-briefing --agent-harness claude-code --allow-overwrite

Briefing layer (agent-instructions.md + harness wrapper)

Per ADR 0148, sdd-cli init and sdd-cli sync emit two files at the SDD root:

• agent-instructions.md — fully method-managed, harness-neutral briefing. Overwritten unconditionally on every sync.
• The harness wrapper — CLAUDE.md under --agent-harness claude-code, AGENTS.md under --agent-harness github-copilot-cli. Thin pointer with <!-- method-managed: begin/end --> markers. The method-managed block is refreshed on sync; adopter content below survives.

Templates ship in the bundle at orchestration/templates/briefing/. Older bundles that pre-date ADR 0148 sync without emitting these files (graceful skip with a log line).

Migration note (v0.21.x → v0.22.0): the legacy generate-claude-md verb retired in favour of generate-briefing. The v0.3–v0.21 native CLAUDE.md renderer is gone — its rich-content shape is replaced by the upstream template-driven thin-pointer shape. Adopters with hand-edited CLAUDE.md files will see sync refuse the wrapper rewrite without --allow-overwrite on first run; rehome any custom content below the method-managed: end marker before sync, or pass --allow-overwrite after backing up.

Agent-harness selection (--agent-harness)

Per ADR 0141, sdd-cli init and sdd-cli sync accept --agent-harness <name> to drive which hook configuration gets emitted. Supported values:

| Value | Hooks surface | MCP surface | |---|---|---| | claude-code (default, reference) | .claude/settings.json hooks block — PreToolUse method-guard + SessionStart ADR-structure check | .claude/settings.json mcpServers block | | github-copilot-cli | .github/hooks/pre-tool-use.json + .github/hooks/session-start.json (per docs/method/methods/hook-contracts.md) | not yet wired — ADR 0150 Phase 3 lands the Copilot-CLI MCP surface |

Adopters using Cursor / Cline / Aider / custom harnesses implement the portable contracts themselves per ADR 0141 §4.5 — see docs/method/onboarding/agent-harness-adopter-responsibility.md in the method baseline.

Behavioural delta: the flag now defaults to claude-code when omitted, where previous versions left it unset (no hooks seeded). The first sdd-cli sync after upgrading on an existing repo will start refreshing the Claude hooks block. The dedupe pre-pass shipped in v0.12.2 collapses any unmarked hand-rolled entries that match the method shape, so adopters on v0.12.2+ get sentinel-tagged-in-place rather than duplicates. Adopters on sdd-cli < v0.12.2 should npm install -g @sdd-method/sdd-cli@latest before re-syncing.

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
• sdd://catalogue/schema — canonical catalogue schema (vendored) as JSON
• sdd://catalogue/metamodel — catalogue metamodel narrative
• sdd://catalogue/category-taxonomy — product category taxonomy
• sdd://catalogue — list of built catalogue names
• sdd://catalogue/{name} — rows of one built catalogue from catalogues/{name}.csv

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
• query_catalogue_coverage — row count + internal-FK pass + coverage for one catalogue
• find_products_by_category — products filtered by category
• find_orphan_rows — rows whose internal FK target is missing
• query_edges_for_entity — every edge row referencing a given entity

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-briefing + briefing + 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.