Skip to content

ValentinNikolaev/agent-skills / agent-plugins/skills/console-ux-design

console-ux-design

Verified

Design or improve command-line and console commands (structure, signatures, help, prompts, progress, errors, output, machine formats, automation), including Artisan and Symfony Console. Not GUIs, terminal themes, full-screen TUIs, shell scripting without UX changes, or report-only audits.

---
name: console-ux-design
description: Design or improve command-line and console commands (structure, signatures, help, prompts, progress, errors, output, machine formats, automation), including Artisan and Symfony Console. Not GUIs, terminal themes, full-screen TUIs, shell scripting without UX changes, or report-only audits.
---

# Console UX Design

Design a predictable console interface for people at a terminal and callers in automation.

## Stay inside the console boundary

- Create or improve ordinary commands, subcommands, and line-oriented console applications.
- Treat Laravel Artisan, Symfony Console, and similar frameworks as examples, not as universal APIs.
- Analyze an existing command when that analysis leads to a redesign or implementation-ready change.
- Do not turn a report-only audit into a redesign. Do not cover web, mobile, native GUI, terminal-emulator themes, or full-screen terminal user interfaces.
- Do not treat shell implementation alone as UX work. Activate only when the command's contract or user experience changes.

## Establish the operating context

Before designing, determine:

- the user's task, domain vocabulary, command frequency, and cost of mistakes;
- novice, expert, and automation journeys;
- current command names, signatures, help, output, exit codes, compatibility promises, and tests;
- supported platforms, shells, console framework, terminal widths, locales, and character encodings;
- TTY and redirected behavior for standard input, output, and error;
- interactive, non-interactive, quiet, verbose, color-disabled, and machine-readable modes;
- destructive effects, secrets, cancellation, partial work, retries, and cleanup obligations.

Mark missing facts and compatibility constraints instead of inventing them.

## Read only the references the task needs

- Read [references/command-contract.md](references/command-contract.md) when defining taxonomy, names, signatures, discoverability, automation behavior, streams, formats, exit codes, aliases, or deprecation.
- Read [references/runtime-interaction-and-output.md](references/runtime-interaction-and-output.md) when defining prompts, confirmation, progress, errors, recovery, text layout, color, verbosity, localization, accessibility, or cancellation.
- Read [references/validation.md](references/validation.md) when planning implementation handoff, acceptance criteria, transcripts, tests, or final verification.
- Read [references/go-cli-contracts.md](references/go-cli-contracts.md) only when the project actually uses Cobra or Viper; detect the installed version before translating the console contract into its APIs.

Read all three for a new command family or an end-to-end redesign. Keep framework-specific syntax in examples and map the resulting contract to the project's actual framework only after inspecting its version and conventions.

## Produce a reviewable design

Deliver the smallest artifact that makes implementation unambiguous. Include, as applicable:

1. user tasks and operating contexts;
2. proposed command tree and signatures;
3. help and completion behavior;
4. interaction states and recovery paths;
5. stream, format, verbosity, color, and terminal-layout rules;
6. exit-code and automation contract;
7. compatibility, migration, and deprecation decisions;
8. implementation notes and acceptance tests.

Show before-and-after transcripts for material changes. Separate required behavior from illustrative wording so reviewers can approve the contract without freezing every sentence.

## Preserve safety and composability

- Never make an interactive prompt the only way to complete a command that is expected to run in automation.
- Never print secrets or mix diagnostics into machine-readable standard output.
- Never rely on color, animation, or cursor control as the sole carrier of meaning.
- Never treat missing input, EOF, ambiguous confirmation, or an unavailable TTY as consent. Permit non-interactive destructive execution only with fully explicit, validated targets and a documented pre-authorized override.
- Define stable success and failure signals before polishing presentation.
- Preserve user data and describe partial-work and cancellation behavior before implementation.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall