create-cli-design

Create CLI Design

Designs the command-line interface for a feature as a companion artifact to the requirements document, settling the commands, subcommands, options, arguments, exit codes, output behavior, help text, and example sessions before implementation begins.

For a CLI, the interface is the product: the user experiences the feature entirely through command syntax, help text, output, and errors. This skill is the terminal counterpart of /create-mockups, which serves features with a graphical interface.

Without this step, CLI work starts with no shared understanding of the command surface, so naming, flags, and output are improvised during implementation and reworked in review.

Prerequisites

• Apply the shared SDLC conventions in skills/sdlc/references/shared.md.
• If no argument is provided, locate the feature directory under .sdlc/features/ whose frontmatter issue field references $ISSUE_NUMBER.
• .sdlc/features/N-<slug>/requirements.md (a draft is acceptable; this skill typically runs delegated from /create-requirements), or a feature brief provided in context or as a file path ($1)
• The repository's existing CLI conventions, when one exists: detect the framework and match its command naming, flag style, and output conventions instead of inventing new ones

Steps

1. Detect revision mode: if review-requirements.md exists beside requirements.md with verdict: changes-requested and its findings concern cli-design.md, read the design and the findings together, amend the design minimally to resolve each finding (preserving content the findings did not challenge), and set frontmatter status: in-review. Skip the fresh drafting below.
2. Read the requirements (or brief) and apply any style rules in .sdlc/context/conventions.md.
3. Survey the existing CLI, if any: framework, command naming, flag style, output conventions, exit code usage. When the project has no CLI yet, fix the baseline conventions explicitly (e.g., GNU-style long options, kebab-case names, verb-first commands) and record them as the design principles.
4. Determine whether the feature has a CLI surface: does it add or change commands, options, or command output? If not, emit verdict: skipped and write no artifact.
5. Derive the command tree from the functional requirements: every user-facing FR maps to at least one command, subcommand, or option; one command per user goal; group related operations under noun subcommands.
6. For each command, specify: a synopsis, a description, positional arguments (name, required, description), options (short and long form, value type, default, env-var fallback), at least one usage example, and its specific error cases.
7. Define the cross-command surface: global options, environment variables, config file and precedence (flags over env over config over defaults), exit codes, the stdout/stderr split, machine-readable output (--json) when scripts must consume the output, and TTY-aware behavior (color, progress, and tables only on a TTY, honoring NO_COLOR).
8. Design user error protection: an actionable error message format (error: <message> plus a hint), confirmation prompts on destructive actions with --yes/--force to skip, and --dry-run where meaningful.
9. Write the help text for the root command and one representative subcommand.
10. Write example sessions as fenced console transcripts demonstrating the intended experience: a happy path, at least one error path, and (for destructive or interactive CLIs) a confirmation exchange plus a piping example. These transcripts are the most important part of the artifact: a reader should be able to picture the experience of using the CLI before it exists.
11. Feed implied changes back: options or commands that surface a missing requirement go into requirements.md as open questions or new FRs, and unresolved interface decisions become open questions here.
12. Write the output to .sdlc/features/N-<slug>/cli-design.md, creating the directory if it does not exist, with frontmatter status: draft.