/commands-standards

name: commands-standards
description: Standards for authoring SDD plugin commands — frontmatter, user interaction, skill/agent invocation, CLI integration, and output formatting.

Commands Standards

Standards for every command in the plugin. Apply when creating or reviewing plugin commands.

---

Scope

This standard applies to commands shipped with the SDD plugin — all `.md` files found in `plugin/core/commands/`. It does not apply to the repo's own `.claude/skills/`.

---

Frontmatter

Every command file must start with YAML frontmatter containing exactly these fields:

---
name: sdd-my-command          # REQUIRED — kebab-case, prefixed with "sdd-"
description: >                # REQUIRED — what this command does, shown in help
  Manage project configuration - generate merged configs,
  validate, diff environments.
---

| Field | Type | Rule | |-------|------|------| | `name` | `string` | kebab-case, prefixed with `sdd-`, matches the filename without `.md` extension | | `description` | `string` | 1-2 sentences. What the command does from the user's perspective. Written for the help listing — concise and action-oriented. |

**No other frontmatter fields.** Additional metadata belongs in the command body.

---

Role of Commands

Commands are the user-facing entry points of the plugin. Users invoke them via `/command-name` in Claude Code. A command's job is to **orchestrate** — not to implement logic directly. Commands:

1. Parse arguments and validate inputs 2. Interact with the user (prompts, confirmations, option selection) 3. Delegate work to skills (via `INVOKE`) and the CLI (via `sdd-system`) 4. Display formatted output and next steps

Commands sit at the top of the invocation hierarchy:

User → Command (user-facing, orchestrates)
Command → Skill (prompt-layer work: solicitation, decomposition, planning)
Command → Agent (specialized implementation: backend-dev, api-designer)
Command → CLI (system-layer work: scaffolding, validation, file operations)

A command must never contain implementation logic that belongs in a skill, agent, or the CLI. If a command's action section grows beyond orchestration (argument parsing, INVOKE directives, state transitions, output formatting), the logic should be extracted into a skill.

---

Self-Containment

A command must be fully understandable on its own. An LLM reading a single command file should know exactly what the command does, what arguments it accepts, what it invokes, and what the user sees — without reading other commands.

Rules

1. **Delegate clearly** — When invoking a skill or agent, state what you pass in and what you expect back. The reader should understand the delegation contract without reading the skill. 2. **Don't duplicate** — Never copy skill definitions, agent workflows, or CLI implementation details into the command. If a skill defines the spec solicitation flow, the command says "INVOKE spec-solicitation" with its inputs — it doesn't reproduce the solicitation steps. 3. **No cross-command file references** — Never reference or read files inside another command's definition. Each command is self-contained. 4. **No environment assumptions** — Do not assume a specific directory structure, tool version, or runtime context unless the command explicitly documents it as a precondition. If the command requires files to exist (e.g., `.sdd/sdd-settings.yaml`), state that as a precondition. 5. **Define your own terms** — If the command introduces domain-specific vocabulary, define it on first use. Don't define terms that belong to skills — delegate instead. 6. **Complete examples** — Every example must be understandable without external context. Include the arguments, expected output, and any state changes. 7. **Plugin boundary** — Plugin commands (`plugin/core/commands/`) have no runtime access to anything outside `plugin/`. Never reference `.claude/`, `.tasks/`, or root-level files from within a plugin command.

---

User Interaction

Commands are the **only** layer that interacts directly with the user. Unlike agents (which have no user channel) and skills (which are instructional context), commands define the conversation flow.

Rules

1. **Explicit interaction points** — Every point where the command pauses for user input must be documented with the exact prompt text and available options. Implicit "ask the user" is not sufficient — show what the user sees. 2. **Options format** — When presenting options, use a numbered list or lettered choices. Always include a cancel/exit option where appropriate. 3. **Confirmation before destructive actions** — Any action that modifies existing files, resets state, or archives artifacts must show a preview and request explicit confirmation. 4. **Progressive disclosure** — Show summaries first, details on request. Don't dump walls of output. Use structured formatting (tables, indented lists, boxed headers) to make output scannable. 5. **Next steps always** — Every terminal output must end with a `NEXT STEPS` section telling the user what to do next. The user should never be left wondering "what now?". 6. **Error messages are actionable** — When validation fails or a precondition is unmet, show what's wrong, why it's wrong, and how to fix it. Never display a raw error without context.

BAD

## Flow
1. Check if branch is main
2. Ask user about the branch
3. Continue

The reader doesn't know what the user sees, what the options are, or what happens for each choice.

GOOD

## Flow
1. Run `git branch --show-current`
2. If on `main`/`master`:

You're on the main branch. Feature work should happen on a feature branch.

Suggested branch: feature/user-auth

[1] Create branch and switch (recommended) [2] Continue on main [3] Cancel

3. If user selects [1]: create and checkout the branch
4. Otherwise proceed on current branch

The reader knows exactly what the user sees and what e