SDD Yo

SDD Yo helps people and AI agents understand a software project through a clear, connected specification. The specification is a graph: it shows what the project does and how its parts relate. This makes it easier to find information and quickly see the whole picture.

You can add SDD Yo to an existing project and build the specification step by step. Every change to the specification or code carries its own context, so several changes can be developed at the same time without confusion.

Exact version 0.5.6 is public on npm and requires Node.js 22.18.0 or newer. Public availability is established only by the npm registry, not by source or README state. The project is pre-1.0, and installing the package does not install or publish a Codex plugin.

Quick start

Requires Node.js 22.18.0 or newer.

For a new SDD Project, first initialize its specification and then validate it. Use incremental adoption unless the specification will govern the entire repository. Initialization creates .sdd/config.yaml, spec/README.md, spec/capabilities/, and spec/concepts/; it does not create a branch or commit. The first validation should return status: "ok" and result.valid: true.

Choose how you want to run SDD Yo:

• use one Codex Skill across repositories on macOS;
• install the Skill in one repository;
• use the npm CLI without a Skill.

Use one Codex Skill across repositories on macOS

Install the Skill once for your macOS user. This does not add sdd-yo to a project or create a global sdd command.

npm exec [email protected] -- sdd skill install --scope user --format json

In Codex, use $sdd-yo to initialize and validate the selected repository. Always provide its absolute path.

To perform the same first steps directly from the terminal:

node ~/.agents/skills/sdd-yo/scripts/check-cli-compatibility -- init --root /absolute/path/to/repository --adoption incremental
node ~/.agents/skills/sdd-yo/scripts/check-cli-compatibility -- validate --cwd /absolute/path/to/repository

The install creates ~/.agents/skills/sdd-yo and a private CLI under ~/Library/Application Support/sdd-yo/cli/<package-version>. The Skill uses only that verified CLI. It does not use PATH, a repository CLI, a package manager, or the network after installation. User mode rejects --cli.

Use the Skill in one repository

Install SDD Yo and its Skill in the selected Git repository:

cd /absolute/path/to/repository
npm install --save-dev --save-exact [email protected]
npm exec -- sdd --version --format json
node ./node_modules/sdd-yo/dist/bin/sdd.js skill install --root /absolute/path/to/repository --format json

This creates /absolute/path/to/repository/.agents/skills/sdd-yo without initializing the project or modifying Git. In Codex, use $sdd-yo to initialize and validate this repository.

To perform the same first steps directly from the terminal:

node ./.agents/skills/sdd-yo/scripts/check-cli-compatibility -- init --root /absolute/path/to/repository --adoption incremental
node ./.agents/skills/sdd-yo/scripts/check-cli-compatibility -- validate --cwd /absolute/path/to/repository

Use the npm CLI without a Skill

Validate an existing SDD Project from the terminal without adding the package or Skill to its repository:

npm exec [email protected] -- sdd --version --format json
npm exec [email protected] -- sdd validate --cwd /absolute/path/to/repository --format json

After installing the package in a repository, use npm exec -- sdd ... to run its local CLI.

The version check should return exit code 0, status: "ok", package and CLI version 0.5.6, and compatible JSON-schema and Skill protocol major 1. Do not rely on a global sdd executable or Skill. User-scoped installation and its public consumer proof are macOS-only.

View workflow progress

The observer turns a workflow-event journal into a temporary local web page and follows later valid journal publications without restart. It shows the stable mode-specific stages for spec-code, accepted-behavior spec, and implementation-only code workflows, detailed steps, and separate approval, readiness, freshness, and integration states without reading logs.

Use this guide after installing an npm package version that includes the observer in the selected repository. The public [email protected] package includes it.

A package built from this source makes its sdd-yo Skill automatically create and publish one mode-scoped journal for each newly selected spec-code, spec, or code workflow. It prints the generated ignored path and run identity; pass that exact path to sdd observe. A code journal is additionally bound to the resolved base object and the exact active Requirement targets with their semantic and structural fingerprints. A spec journal instead binds the exact accepted behavior and intended QA plan without treating either as evidence. Non-Change routes do not create automatic journals. This automatic production is repository-source behavior and has not created a new npm release.

Library or CLI integrations can create the same bounded journal explicitly:

npm exec -- sdd journal create --cwd /absolute/path/to/repository \
  --workflow-mode spec-code --producer my-integration

For an implementation-only correction, select the base and every exact target when the journal is created:

npm exec -- sdd journal create --cwd /absolute/path/to/repository \
  --workflow-mode code --producer my-integration --base main \
  --code-target REQ-XXXXXXXX

For accepted existing behavior, bind the descriptive subject and intended QA plan when the journal is created:

npm exec -- sdd journal create --cwd /absolute/path/to/repository \
  --workflow-mode spec --producer my-integration \
  --accepted-behavior "Existing export is accepted" \
  --qa-plan "Verify the exported document"

Retain the returned journal path, subject, next sequence, and fingerprint. Resume only that exact subject with sdd journal resume, and publish typed events with sdd journal publish plus the returned expected sequence and fingerprint. A stale or competing writer fails without replacing the last complete JSONL publication.

Start the observer with the generated path:

npm exec -- sdd observe --cwd /absolute/path/to/repository \
  --journal .sdd/staging/workflow-observation/<mode>/<run-id>.jsonl

You do not need to choose a port. SDD Yo asks the operating system for an available local port and prints the complete http://127.0.0.1:... URL. Keep the command running while the page is open, and press Ctrl-C when you are done. The URL contains a private session capability; do not share it.

Valid later atomic publications update the same page live. A malformed, stale, or conflicting update leaves the last valid snapshot visible and reports a separate observer condition. Reconnect resumes after the last delivered sequence without duplicating a completed boundary.

The observer is read-only. In particular, a code view has exactly seven stages: workflow initialization and targets, code proposal, proposal decision, implementation, verification and review, local integration, and terminal outcome. It has no semantic-model, authored-candidate, branch-preparation, or SpecPatch stage. A spec view has exactly eight stages, omits implementation, and reports implementation as not applicable. The observer cannot approve a proposal, run a gate, change Git, publish, or release. Its journal and snapshot are removable display data, not approval or merge evidence.

Use as a library

The npm package provides an ESM library, TypeScript declarations, the sdd CLI, and versioned JSON Schemas.

import { JSON_SCHEMA_VERSION_V1 } from "sdd-yo";

console.log(JSON_SCHEMA_VERSION_V1); // "1.0"

Versioned schemas are available through paths such as sdd-yo/schemas/v1/common.schema.json.

Offline installation

Install an approved exact tarball without registry fallback:

npm install --offline --no-audit --no-fund --save-exact <tarball-path>
node ./node_modules/sdd-yo/dist/bin/sdd.js --version --format json

Require the same version and protocol identity described above.

Yarn Plug'n'Play

The Skill requires a physical packaged CLI inside the repository. Keep SDD Yo out of the Yarn dependency graph and place it in an ignored npm consumer:

mkdir .sdd-tooling
mkdir .sdd-tooling/consumer
cd .sdd-tooling/consumer
npm init --yes
npm install --offline --no-audit --no-fund --save-exact <tarball-path>
cd ../..
node ./.sdd-tooling/consumer/node_modules/sdd-yo/dist/bin/sdd.js --version --format json
node ./.sdd-tooling/consumer/node_modules/sdd-yo/dist/bin/sdd.js skill install --root <repository-root> --format json

Add .sdd-tooling/ to .gitignore. Keep .agents/, .sdd/, and spec/ as reviewable project changes. For direct CLI commands, substitute ./.sdd-tooling/consumer/node_modules/sdd-yo for ./node_modules/sdd-yo.

Automation

Call the packaged CLI with an explicit project root and JSON output:

node ./node_modules/sdd-yo/dist/bin/sdd.js validate --cwd <repository-root> --format json

Use schema_version, status, diagnostics[].code, and the typed result as the API; do not parse English output. Exit codes are 0 for a completed non-blocking result, 1 for blocked, 2 for human review, and 3 for an invocation, configuration, I/O, protocol, or internal failure.

Planning broad work with the Skill

Ask $sdd-yo to plan an initiative when the desired outcome spans several Capabilities or needs multiple independently deliverable Changes. The expected result is an advisory ID-free map with proportionate design depth, explicit boundaries and risks, and an ordered set of independently valuable vertical slices.

No project is required for generic planning, and that path invokes no SDD CLI operation. When you explicitly select an SDD Project, the Skill validates it and inspects only the smallest relevant active specification slice. The map stays conversational unless you explicitly request a project-local planning file. Select one slice to enter the existing governed spec-code, spec, or code workflow; planning itself creates no specification object, approval, evidence, patch, or Git authority.

Skill lifecycle

After installing the selected exact package, update or remove its verified repository Skill with:

node ./node_modules/sdd-yo/dist/bin/sdd.js skill update --root <repository-root> --format json
node ./node_modules/sdd-yo/dist/bin/sdd.js skill remove --root <repository-root> --format json

These commands refuse modified, stale, incompatible, unsafe, or undeclared installation bytes. Removal leaves the npm package, .sdd, spec, Git, and adjacent repositories untouched.

On macOS, update or remove the independently selected user installation with:

node ./node_modules/sdd-yo/dist/bin/sdd.js skill update --scope user --format json
node ./node_modules/sdd-yo/dist/bin/sdd.js skill remove --scope user --format json

User lifecycle commands verify both the Skill and private CLI inventories. They refuse modified, missing, foreign, ambiguous, or incomplete recovery state without falling back to a repository installation.

Common diagnostics

| Code | Action | | -------------------------------------------- | ------------------------------------------------------------------------------- | | SDD_CONFIG_NOT_FOUND | Correct the explicit project selector; initialize only when intended. | | SDD_INIT_TARGET_CONFLICT | Preserve existing bytes and resolve the conflicting target. | | SDD_INIT_ROOT_INVALID | Select an existing directory. | | SDD_INIT_TARGET_UNSAFE | Stop and correct the unsafe target. | | SDD_GIT_REF_UNRESOLVED | Fetch or correct the exact requested Git ref. | | SDD_USER_SKILL_PLATFORM_UNSUPPORTED | Use user scope only on macOS; do not substitute a global install. | | SDD_USER_SKILL_PACKAGE_INVALID | Preserve both stores and select the reviewed exact package bytes. | | SDD_USER_SKILL_LIFECYCLE_OWNERSHIP_INVALID | Preserve modified or foreign bytes; do not overwrite or delete. | | SDD_USER_SKILL_RECOVERY_REQUIRED | Retry only the intended explicit lifecycle command to reconcile verified state. |

For Skill lifecycle failures, correct the reported root, compatibility, binding, or owned-byte mismatch; never bypass verification with a global installation or silent overwrite. See the diagnostics catalog for details.

Authority boundaries

Deterministic CLI results do not create or imply human approval, semantic review, QA, test execution, finding resolution, patch permission, or merge permission. A PASS applies only to the report's exact governed scope and evidence; it is not whole-project certification.

Only identified humans can issue approval and QA evidence. SDD Yo never creates branches, commits, pushes, merges, approvals, or QA decisions implicitly.

See the specification for implemented behavior and the architecture map for implementation contracts.

Development

Install locked dependencies with npm ci. See CONTRIBUTING.md for validation and contribution guidance, CODE_OF_CONDUCT.md for community standards, and SECURITY.md for private vulnerability reporting.

License

Licensed under the Apache License 2.0. Copyright 2026 Ivan Briginas.