From 3a8f333c221b0d1fdffa95f4805e696900931106 Mon Sep 17 00:00:00 2001
From: Eden Zimbelman <eden.zimbelman@salesforce.com>
Date: Thu, 19 Mar 2026 21:44:40 -0700
Subject: [PATCH] docs(maintainers): add style guide for input and output

---
 .claude/CLAUDE.md            |  4 ++++
 .github/MAINTAINERS_GUIDE.md |  7 +++++++
 .github/STYLE_GUIDE.md       | 40 ++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 .github/STYLE_GUIDE.md

diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index 2d98aa22..9dd3ecf4 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -189,6 +189,10 @@ When deprecating features, commands, or flags:
 3. **Public functionality**: Add comment `// DEPRECATED(semver:major): <description and migration path>`
 4. **Internal functionality**: Add comment `// DEPRECATED: <description>`
 
+## Style Guide
+
+See [`.github/STYLE_GUIDE.md`](../.github/STYLE_GUIDE.md) for conventions on command inputs and outputs.
+
 ## Important Configuration Files
 
 - `.golangci.yml` - Linter configuration with custom initialisms (CLI, API, SDK, etc.) and staticcheck rules
diff --git a/.github/MAINTAINERS_GUIDE.md b/.github/MAINTAINERS_GUIDE.md
index 2f9d5f90..604516cf 100644
--- a/.github/MAINTAINERS_GUIDE.md
+++ b/.github/MAINTAINERS_GUIDE.md
@@ -294,6 +294,7 @@ Certain things are common during development and require a few commands.
   - [Bumping the Golang version](#bumping-the-golang-version)
   - [Bumping Go packages versions](#bumping-go-package-versions)
   - [Bumping Goreleaser versions](#bumping-goreleaser-versions)
+- [Designing](#designing)
 - [Deprecating features and flags](#deprecating-features-and-flags)
 - [Allowlist configuration](#allowlist-configuration)
 
@@ -632,6 +633,11 @@ updates in the following files on occasion:
 
 Testing in our CI setup uses changes to these files when creating test builds.
 
+### Designing
+
+Conventions for how commands handle inputs and format outputs are documented in
+the [style guide][style-guide].
+
 ### Deprecating features and flags
 
 Many good things come to an end. This can sometimes include commands and flags.
@@ -926,6 +932,7 @@ When in doubt, find the other maintainers and ask.
 [practical-go]: https://dave.cheney.net/practical-go/presentations/qcon-china.html
 [scripts]: ../scripts
 [semver]: https://semver.org/
+[style-guide]: ./STYLE_GUIDE.md
 [sync]: https://github.com/slackapi/slack-cli/blob/main/.github/workflows/sync-docs-from-cli-repo.yml
 [vscode]: https://github.com/slackapi/slack-cli/blob/main/.vscode/settings.json
 [wf-dependencies]: ./workflows/dependencies.yml
diff --git a/.github/STYLE_GUIDE.md b/.github/STYLE_GUIDE.md
new file mode 100644
index 00000000..2ecc130e
--- /dev/null
+++ b/.github/STYLE_GUIDE.md
@@ -0,0 +1,40 @@
+# Style Guide
+
+A current suggestion for how Slack CLI inputs are handled and outputs are formatted.
+
+- **Input**
+  - [Prompts are Flags with Forms](#prompts-are-flags-with-forms)
+- **Output**
+  - [Format Sections with Command Details](#format-sections-with-command-details)
+
+## Input
+
+Customizations to commands are made through arguments, flags, environment variables, saved files, details from the Slack API itself, or sometimes just kept as "sensible" defaults.
+
+### Prompts are Flags with Forms
+
+When information is needed we can prompt for text, confirmation, or a selection.
+
+These decisions can be made in an interactive terminal (TTY) or not, such as in a scripting environment.
+
+A flag option should exist for each prompt with a form fallback. Either default values should be used if forms are attempted in a non-TTY setup or an error and remmediation to use a flag should be returned.
+
+## Output
+
+Results of a command go toward informing current happenings and suggesting next steps.
+
+### Format Sections with Command Details
+
+A command often prints information and details about the process happenings. We format this as a section:
+
+```txt
+📚 App Install
+   Installing "focused-lamb-99" app to "devrelsandbox"
+   Finished in 2.0s
+```
+
+This example highlights some recommendations:
+
+- An emoji is used with the section header.
+- The section header text is the command name, with "Title Case" letters.
+- Following details reveal progress of the process.