specdd-cli.sdd

Spec: specdd-cli Agent Skill
Purpose:
  Teach agents how to use the specdd CLI for SpecDD-oriented repository work, including setup or update when explicitly requested, and day-to-day finding, inspecting, and validating specs.

Owns:
  ./specdd-cli/SKILL.md.ejs
  ./specdd-cli/agents/openai.yaml

Must:
  Present `specdd resolve`, `specdd inspect`, and `specdd lint` as the primary agent commands.
  Present `specdd init` and `specdd update` as setup and framework-update commands only when the operator explicitly asks to add or update SpecDD.
  Explain that `specdd init [path]` initializes SpecDD in the current directory or target directory and adds SpecDD only when `.specdd/bootstrap.md` is not already present.
  Explain that `specdd update` updates an existing SpecDD project and requires the current directory to contain `.specdd/bootstrap.md`.
  Explain that `specdd init` and `specdd update` accept `--version <version>` to use a specific SpecDD release version.
  Tell agents to reread affected bootstrap files after `specdd update` only when the update changed framework files.
  Prefer `specdd resolve` over grep, find, or broad file reads when the task has a concrete target path.
  Prefer `specdd inspect` over grep, find, or broad file reads when the task needs an overview of specs under a directory.
  Use `specdd lint` after creating or editing `.sdd` files.
  Treat specs as source-adjacent contracts, not optional documentation.
  Tell agents to run commands from the project root when possible.
  Tell agents to pass `--root <project>` when running from outside the project root or when the target path is absolute.
  Explain that targets for `resolve`, `inspect`, and `lint` must exist.
  Explain that target paths may be directories, `.sdd` spec files, or ordinary files.
  Explain that ordinary file targets resolve a same-basename `.sdd` file when one exists.
  Explain that directory-level context can include parent-held specs such as `src/apps/travel-planner.sdd` and local specs such as `src/apps/travel-planner/travel-planner.sdd`.
  Explain that parent-held and local directory-level specs are cumulative context, not alternatives.
  Explain that root-level project specs follow the selected root directory basename convention.
  Explain that command text output is for humans and compact JSON output is for tools.
  Recommend `--format json` when the agent needs stable machine-readable output.
  Recommend `--format json-extended` only when parser metadata, line numbers, raw entries, or full service result shape are needed.
  Recommend explicit `--section` or `--sections` filters to avoid noisy output.
  Explain that `--sections all` and `--section all` request every canonical SpecDD section.
  Recommend `--sections all` when the agent needs the complete local contract and output volume is acceptable.
  Recommend asking for `--sections all` when the agent needs implementation authority and behavior context.
  Explain that `resolve` follows only explicit local paths beginning with `./`, `../`, or `/`.
  Explain that `resolve` follows soft links from `Owns`, `Can modify`, `Can read`, `References`, `Depends on`, and `Structure`.
  Explain that `resolve` does not follow `Forbids` or `Exposes` as relevance links.
  Explain that non-glob directory links resolve only to the directory-level specs for that directory.
  Explain that recursive descendant inclusion requires explicit globs such as `./**` or `./**/*.sdd`.
  Explain the default `resolve` depth of `2`.
  Explain `--depth 0` as vertical context only.
  Explain `--depth 1` as direct links from the target spec only.
  Explain `--depth 2` as target links plus immediate parent context links.
  Explain `--depth all` as recursive reachable links with cycle protection.
  Tell agents to lower depth when broad parent links make output too noisy.
  Tell agents to increase depth only when the task requires deeper linked context.
  Tell agents to inspect before authoring new specs if the appropriate local spec boundary is unclear.
  Tell agents to resolve before modifying code when there is a concrete file, directory, or spec target.
  Tell agents to lint the narrowest edited spec path first, then lint the relevant directory when the change affects multiple specs.
  Tell agents to use CLI output to decide what specs to read or reread when exact contract text matters, not to reread every discovered spec by default.
  De-emphasize `check-update` and `agentskills deploy` for day-to-day agent implementation work unless the user explicitly asks for update-check, release, or skill installation behavior.

Must not:
  Tell agents to use grep or recursive file reads as the first step for SpecDD context discovery when `specdd resolve` or `specdd inspect` can answer the question.
  Tell agents that `resolve` grants write authority by itself.
  Tell agents to modify files only because they appear in `resolve` output.
  Tell agents to reread every resolved spec by default.
  Tell agents to ignore active bootstrap files or local `.sdd` contracts.
  Tell agents to use `--depth all` by default.
  Tell agents that non-glob directory links recursively include all descendant specs.
  Treat `init`, `update`, `check-update`, or `agentskills deploy` as the core workflow for coding agents.
  Present CLI output as a substitute for validating edited specs with `specdd lint`.
  Encourage agents to continue after `specdd lint` reports errors in edited specs.

Handles:
  adding SpecDD bootstrap files when the operator asks for setup
  updating SpecDD framework bootstrap files when the operator asks for updates
  orienting before a code change
  orienting before a spec change
  finding relevant specs for a file target
  finding relevant specs for a directory target
  inspecting a subtree of specs
  validating a newly created spec
  validating an edited spec
  reducing noisy context output
  producing machine-readable context for tools
  avoiding broad grep-based discovery
  choosing root and depth arguments
  understanding parent-held and local directory specs

Scenario: orient to a concrete source file
  Given an agent needs to work on `src/apps/travel-planner/travel-planner.ts`
  When the file exists in a SpecDD project
  Then the skill tells the agent to run `specdd resolve --root <project> src/apps/travel-planner/travel-planner.ts`
  And the skill tells the agent to add section filters when it needs authority or behavior details
  And the skill tells the agent to read or reread only the resolved governing specs needed for the requested decision

Scenario: inspect a spec area
  Given an agent needs an overview of specs under `src/apps`
  When the agent does not have one concrete target file
  Then the skill tells the agent to run `specdd inspect src/apps --sections Purpose,Owns,Must,Tasks`
  And the skill tells the agent to use `--sections all` when it needs the complete spec content
  And the skill tells the agent to use text output for human scanning
  And the skill tells the agent to use `--format json` for structured tooling

Scenario: validate edited specs
  Given an agent creates or edits `.sdd` files
  When the edit is complete
  Then the skill tells the agent to run `specdd lint <changed-spec-or-directory>`
  And the skill tells the agent to fix syntax errors before reporting completion
  And the skill tells the agent to run a broader lint target when the change affects multiple specs

Scenario: noisy resolve output
  Given `specdd resolve` output includes too much linked context
  When broad parent links or globs are the likely cause
  Then the skill tells the agent to retry with `--depth 0` or `--depth 1`
  And the skill tells the agent to increase depth only when deeper soft-link context is needed

Example: primary resolve commands
  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.sdd --sections Purpose,Owns,Can modify,Must,Must not
  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

Example: primary inspect commands
  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,Tasks
  specdd inspect src/apps --sections all
  specdd inspect src/apps --format json
  specdd inspect src/apps --format json-extended

Example: primary lint commands
  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

Example: recommended agent workflow
  Resolve relevant specs for a concrete target before editing.
  Inspect a directory when choosing where a new spec should live.
  Read or reread exact specs when relying on their constraints.
  Edit the smallest authorized set of files.
  Run `specdd lint` on changed specs.
  Report the commands used and whether lint passed.

Done when:
  Agents know to use `init` or `update` only when setup or framework updates are explicitly requested.
  Agents understand that `resolve`, `inspect`, and `lint` are the core SpecDD CLI commands for implementation and spec-authoring work.
  Agents can choose target, root, depth, section, and format options correctly.
  Agents know to use `--sections all` for complete spec output when needed.
  Agents prefer CLI-assisted SpecDD discovery over broad grep-style discovery.
  Agents validate new or edited specs with `specdd lint`.

Depends on:
  ../fragments/specdd-skill-scope.md.ejs