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

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 each option does.

Skill and Agent Invocation

Commands delegate work to skills and agents using the INVOKE directive. This is the standard format for documenting delegation in command files.

INVOKE format

INVOKE <skill-or-agent-name> with:
  param1: <value or description>
  param2: <value or description>

For skills with methods (e.g., workflow-state):

INVOKE <skill-name>.<method> with:
  param1: <value>

Rules

1. Every INVOKE must specify inputs — List every parameter the skill or agent receives. Use <angle brackets> for dynamic values and plain text for literals.
2. Document expected output — After the INVOKE, state what the command expects back (e.g., "Returns workflow_id for tracking."). The reader should know the shape of the result without reading the skill.
3. Only invoke skills and agents that exist — Every skill name in the command must correspond to an actual SKILL.md somewhere under plugin/core/skills/ or plugin/fullstack-typescript/skills/ (scan recursively). Every agent name must correspond to an .md file in plugin/fullstack-typescript/agents/. Referencing nonexistent skills or agents creates silent failures.
4. Invocations are sequential within a flow — Document invocations in the order they execute. If an invocation depends on a previous result, show the data flow explicitly (e.g., workflow_id: <from step 3>).
5. No inline skill logic — If you find yourself writing the steps a skill performs inside the command, you're duplicating. Replace with an INVOKE and a one-line summary of what the skill returns.

CLI Integration

Commands may call the sdd-system CLI for deterministic, system-layer operations (file creation, validation, version bumping). This is a different delegation path than INVOKE — CLI calls are shell executions, not prompt-layer context loading. For the canonical invocation pattern, output contracts, and authority boundaries, see the system-cli-standards skill.

Format

## Implementation

This command invokes `sdd-system` CLI subcommands:

```bash
sdd-system <namespace> <action> [args] [options]

Or inli