Specdd CLI

SpecDD CLI

Use this skill to explore and work with SpecDD projects using the specdd CLI.

Prefer the CLI for SpecDD context discovery because it understands target paths, directory spec conventions, selected roots, section filters, soft-link depth, and spec linting.

This skill is for day-to-day agent implementation and spec-authoring work, plus setup or framework updates when the operator explicitly asks for them. It does not make CLI output a write-authority grant, and it does not make setup, update, release, or skill-installation commands part of the normal coding workflow.

Skill Scope

Use this skill only for projects that already have a root .specdd/bootstrap.md and are therefore SpecDD projects.

If .specdd/bootstrap.md is missing, do not continue with this skill. Use specdd-adopt only when the operator explicitly asks to add or adopt SpecDD in a new or existing non-SpecDD project.

CLI Availability

Ensure CLI is installed by running command -v specdd.

If specdd is missing, do not install it automatically.

Report that CLI exploration is unavailable, then continue with normal bootstrap and spec-chain resolution.

Available Commands

The primary day-to-day agent commands are resolve, inspect, and lint. Use init or update only when the operator explicitly asks to add or update SpecDD framework files. Prefer resolve or inspect over grep, find, or broad recursive file reads when those commands can answer the SpecDD context question. Use raw search for non-spec source symbols, implementation details, logs, tests, or when the CLI is unavailable or too narrow for the user-requested literal search.

specdd init

specdd init answers "add SpecDD framework bootstrap files here." Use it when the operator explicitly asks to add SpecDD to a project and .specdd/bootstrap.md is not already present. It initializes SpecDD in the current directory or target directory, creates the target directory when needed, and does not add SpecDD when .specdd/bootstrap.md already exists.

Usage:

specdd init [path] [--version version]

Arguments:

• path: Target directory to initialize. If omitted, the current directory is used.

Command-specific options:

• --version version: Use a specific SpecDD release version, such as 1.2 or 1.2.3, without a leading v.

Example:

specdd init
specdd init /path/to/travel-planner
specdd init --version 1.2.3

After initialization, read the new bootstrap chain before proposing or creating local .sdd specs.

specdd update

specdd update answers "update this project's SpecDD framework bootstrap files." Use it only when the operator explicitly asks to update SpecDD framework files. The current directory must contain .specdd/bootstrap.md. With the default latest release, it compares the local bootstrap Version front matter with the latest release and does nothing when the local version is already current or newer.

Usage:

specdd update [--version version]

Command-specific options:

• --version version: Use a specific SpecDD release version, such as 1.2 or 1.2.3, without a leading v.

Example:

specdd update
specdd update --version 1.2.3

If specdd update changed framework files, reread the affected bootstrap files before continuing SpecDD work.

specdd resolve

specdd resolve answers "which specs are relevant to this concrete target?" Use it when the task has a concrete file, directory, or .sdd target and the agent needs the relevant SpecDD context for that target before reading exact specs or editing code. It starts from an existing target, collects vertical SpecDD context from the target up to the selected root, includes same-basename and directory-level specs where applicable, expands soft links according to --depth, and prints selected sections from the resulting relevant specs.

Usage:

specdd resolve target [--root path] [--section name] [--sections names] [--depth depth] [--format format]

Arguments:

• target: Existing directory, .sdd file, or ordinary file to resolve. This argument is required.

Command-specific options:

• --root path: Set the resolution root directory. Relative / paths in specs are resolved from this root. The default is the current directory. Run commands from the project root when possible; when running from outside the project root, or when using an absolute target path, pass --root <project>.
• --section name: Include a section by name, or all. May be repeated.
• --sections names: Include comma-separated section names, or all to include every SpecDD section present in each spec.
• --depth depth: Control how far resolve expands soft links. The default is 2. Use 0 for vertical context only, 1 for direct links from the target spec only, 2 for target links plus immediate parent context links, 3 to also expand the next parent context level, or all to recursively follow all reachable links with cycle protection.
• --format format: Set output format. Supported values are text, json, and json-extended. The default is text. Compact JSON omits parser metadata. Extended JSON includes the full internal service result.

Important resolution behavior:

• Ordinary file targets resolve a same-basename .sdd file when one exists.
• Directory context can include a parent-held spec such as src/apps/travel-planner.sdd and a local directory spec such as src/apps/travel-planner/travel-planner.sdd.
• Parent-held and local directory-level specs are cumulative context, not alternatives.
• Root-level project specs follow the selected root directory basename convention, such as /path/to/travel-planner using /travel-planner.sdd.
• resolve follows explicit local paths beginning with ./, ../, or /.
• resolve follows soft links from Owns, Can modify, Can read, References, Depends on, and Structure.
• resolve does not follow Forbids or Exposes as relevance links.
• Non-glob directory links resolve only to the directory-level specs for that directory.
• Recursive descendant inclusion requires explicit globs such as ./** or ./**/*.sdd.
• Use explicit --section or --sections filters to avoid noisy output.
• Use --sections all or --section all when complete local contract output is needed and output volume is acceptable.
• Use text output for human scanning.
• Use --format json when stable machine-readable output is needed.
• Use --format json-extended only when parser metadata, line numbers, raw entries, or the full service result shape are needed.
• Lower --depth when broad parent links or globs make output too noisy.
• Increase --depth only when the task requires deeper linked context.
• Do not use --depth all by default.

Examples:

specdd resolve src/apps/travel-planner/travel-planner.ts
specdd resolve --root /path/to/travel-planner /path/to/travel-planner/src/apps/travel-planner
specdd resolve src/apps/travel-planner/travel-planner.ts --sections Purpose,Owns,Can modify,Must,Must not,Tasks
specdd resolve src/apps/travel-planner/travel-planner.sdd --sections all
specdd resolve src/apps/travel-planner --depth 0
specdd resolve src/apps/travel-planner --depth 1 --format json
specdd resolve src/apps/travel-planner --format json-extended

Use resolve before modifying code when there is a concrete target path. Use CLI output to decide which specs matter, then read or reread the specific governing specs only when you need exact contract text for write authority, behavior, or stop conditions. Do not treat specdd resolve output as write authority by itself, and do not modify files only because they appear in resolve output.

specdd inspect

specdd inspect answers "what specs exist here and what do their selected sections say?" It discovers .sdd files for an existing target path and prints selected sections in a tree-shaped report. Use it to map a subtree, inspect a specific spec, inspect the spec context for an ordinary file, or choose where a new spec should live before authoring.

Usage:

specdd inspect [path] [--section name] [--sections names] [--format format]

Arguments:

• path: Existing directory, .sdd file, or ordinary file to inspect. If omitted, the current directory is inspected.

Options:

• --section name: Include a section by name, or all. May be repeated.
• --sections names: Include comma-separated section names, for example Purpose,Must,Tasks. Use all to include every SpecDD section present in each spec.
• --format format: Set output format. Supported values are text, json, and json-extended. The default is text. Compact JSON omits parser metadata. Extended JSON includes the full internal service result.

Important inspect behavior:

• inspect is for mapping and reading selected sections, not for granting write authority.
• Inspect before authoring new specs if the appropriate local spec boundary is unclear.
• Use explicit --section or --sections filters to avoid noisy output.
• Use --sections all or --section all when complete spec content is needed and output volume is acceptable.
• Use text output for human scanning.
• Use --format json when stable machine-readable output is needed.
• Use --format json-extended only when parser metadata, line numbers, raw entries, or the full service result shape are needed.

Examples:

specdd inspect
specdd inspect src/apps
specdd inspect src/apps/travel-planner/travel-planner.sdd
specdd inspect src/apps/travel-planner/travel-planner.ts
specdd inspect src/apps --sections Purpose,Structure,Owns,Must,Tasks
specdd inspect src/apps --sections all
specdd inspect src/apps --format json
specdd inspect src/apps --format json-extended

specdd lint

specdd lint answers "are these specs syntactically valid?" It lints .sdd files for an existing target path, reports SpecDD syntax and parser diagnostics, and returns a failing status when lint errors are present. Use it after creating or editing .sdd files.

Usage:

specdd lint [path] [--format format]

Arguments:

• path: Existing directory, .sdd file, or ordinary file to lint. If omitted, the current directory is linted.

Options:

• --format format: Set output format. Supported values are text and json. The default is text.

Important lint behavior:

• Text output prints only files with diagnostics.
• Lint the narrowest edited spec path first, then lint the relevant directory when the change affects multiple specs.
• Fix lint errors in edited specs before reporting completion.

Examples:

specdd lint
specdd lint src/apps/travel-planner/travel-planner.sdd
specdd lint src/apps/travel-planner
specdd lint src/apps/travel-planner --format json

Do not present CLI output as a substitute for validating edited specs with specdd lint.

Common Behavior

Target behavior:

• Explicit targets and paths must exist.
• Target paths may be directories, .sdd spec files, or ordinary files.
• Root-level project specs follow the containing directory basename convention.
• Directory blocks can include parent-held directory specs such as src/apps/travel-planner.sdd and local directory specs such as src/apps/travel-planner/travel-planner.sdd when both govern the same directory.

Exit status:

• Exit status 0 means the command completed successfully.
• Exit status 1 means a user-visible non-success result, such as lint errors from lint.
• Exit status greater than 1 means invalid input, missing prerequisites, download or verification failure, filesystem failure, or another unexpected error.

Boundaries

• Treat specs as source-adjacent contracts, not optional documentation.
• Do not ignore active bootstrap files or local .sdd contracts.
• Do not tell agents to use grep or recursive file reads as the first step for SpecDD context discovery when resolve or inspect can answer the question.
• Do not tell agents that resolve grants write authority by itself.
• Do not tell agents that non-glob directory links recursively include all descendant specs.
• Use specdd init and specdd update only when the operator explicitly asks for setup or framework-update behavior.
• De-emphasize specdd check-update and specdd agentskills deploy unless the user explicitly asks for update-check, release, or skill-installation behavior.

Reporting

Report the CLI commands used, the relevant output summary, any specs read or reread directly, whether lint passed for edited specs, and any remaining authority or verification gap.