Add capitalization consistency tests and documentation by Copilot · Pull Request #3730 · github/gh-aw

Copilot · 2025-11-12T14:36:51Z

Fix CLI Capitalization Consistency ✅

Summary

After thorough analysis, the CLI already follows Option 2 correctly (lowercase "agentic workflows" for generic usage, capitalized "Agentic Workflows" only for product name). This PR adds automated tests and documentation to maintain consistency.

Changes

1. Automated Tests (`cmd/gh-aw/capitalization_test.go`)

TestCapitalizationConsistency: Verifies product name uses capitalized "GitHub Agentic Workflows" while generic usage uses lowercase "agentic workflows"
TestMCPCommandCapitalization: Tests MCP subcommands specifically
TestTechnicalTermsCapitalization: Ensures technical terms (Markdown, YAML, MCP) stay capitalized
Simplified test logic based on PR feedback
All tests pass ✅

2. Documentation (`docs/src/content/docs/reference/capitalization.md`)

Moved to proper Astro Starlight structure
Follows Diátaxis framework (Explanation-oriented)
Proper frontmatter with title, description, sidebar order
Explains design rationale and historical context
Provides clear examples and implementation details

Addressed PR Feedback

✅ Fixed unreachable code (lines 66-71) by simplifying test logic
✅ Removed empty if block (lines 24-27)
✅ Simplified overly complex test logic to directly check for incorrect usage
✅ Moved documentation to Astro structure: docs/src/content/docs/reference/capitalization.md
✅ Restructured documentation to follow Diátaxis framework
✅ All linting passes

Verification

Product Name (Capitalized) ✅

Root command: "GitHub Agentic Workflows CLI from GitHub Next"
Version command: "GitHub Agentic Workflows CLI from GitHub Next"

Generic Usage (Lowercase) ✅

enable: "Enable agentic workflows"
disable: "Disable agentic workflows and cancel any in-progress runs"
status: "Show status of agentic workflows"
init: "Initialize repository for agentic workflows"
logs: "Download and analyze agentic workflow logs with aggregated metrics"
All MCP commands use lowercase

Technical Terms (Capitalized) ✅

compile: "Compile Markdown to YAML workflows"
mcp: "MCP helpers"

Test Results

$ make lint
✓ All validations passed

$ make test-unit
PASS
ok  	github.com/githubnext/gh-aw/cmd/gh-aw	0.089s
ok  	github.com/githubnext/gh-aw/pkg/workflow	10.795s

No code changes required - the codebase already implements Option 2 correctly.

Original prompt

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Inconsistent capitalization of "agentic workflows" in command descriptions</issue_title>
<issue_description>## Issue Description

Type: Style inconsistency
Priority: Low
Scope: Multiple command Short descriptions

Current State

Command descriptions in the CLI use inconsistent capitalization when referring to "agentic workflows" and the product "Agentic Workflows".

Examples of Inconsistency

Lowercase "agentic workflows" (generic usage):

enable command: "Enable agentic workflows"

disable command: "Disable agentic workflows and cancel any in-progress runs"

status command: "Show status of agentic workflows"

init command: "Initialize repository for agentic workflows"

logs command: "Download and analyze agentic workflow logs with aggregated metrics"

Capitalized "Agentic Workflows" (product name):

Root command: "GitHub Agentic Workflows CLI from GitHub Next"

Capitalized technical terms:

compile command: "Compile Markdown to YAML workflows"

Uses "Markdown" and "YAML" capitalized (correct for proper nouns/acronyms)

Issue

The inconsistency makes it unclear whether:

"Agentic Workflows" should always be capitalized as a product name

"agentic workflows" should be lowercase when used generically

There's a mixed approach depending on context

Recommendation

Choose one of these approaches and apply it consistently:

Option 1 - Always capitalize as product name:
Enable Agentic Workflows
Disable Agentic Workflows and cancel any in-progress runs
Show status of Agentic Workflows
Initialize repository for Agentic Workflows
Option 2 - Capitalize only when explicitly referring to the product:
Enable agentic workflows (generic usage - lowercase)
GitHub Agentic Workflows CLI (product name - capitalized)
Option 3 - Use "workflows" generically, "Agentic Workflows" for product:
Enable workflows
Disable workflows and cancel any in-progress runs
Show workflow status
Initialize repository for agentic workflows
Suggested Approach

Option 2 seems most appropriate:

Use lowercase "agentic workflows" when referring generically to the workflow files/functionality

Use capitalized "Agentic Workflows" only when explicitly referring to the product as a whole

Keep technical terms like "Markdown", "YAML", "MCP" capitalized

Files Affected

cmd/gh-aw/main.go - enable, disable commands

pkg/cli/status.go - status command

pkg/cli/init.go - init command (via init_command.go)

pkg/cli/logs.go - logs command

Impact

This is a minor style issue that doesn't affect functionality, but consistency in messaging improves the professional appearance of the CLI and makes it easier to understand when referring to the product vs. the concept.

AI generated by CLI Consistency Checker</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes [cli-consistency] Inconsistent capitalization of "agentic workflows" in command descriptions #3711

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

- Add comprehensive tests in cmd/gh-aw/capitalization_test.go - Create CAPITALIZATION_GUIDELINES.md documentation - Verify existing code already follows Option 2 correctly Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot

Pull Request Overview

This PR documents and enforces capitalization consistency for "agentic workflows" vs "Agentic Workflows" in CLI command descriptions. After verifying the codebase already follows the desired pattern (lowercase for generic usage, capitalized for product name), the PR adds automated tests and comprehensive documentation to prevent future inconsistencies.

Key Changes:

Adds automated tests to enforce capitalization rules
Documents the decision in a comprehensive guideline file

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
docs/CAPITALIZATION_GUIDELINES.md	Comprehensive guideline documenting when to capitalize "Agentic Workflows" vs "agentic workflows"
cmd/gh-aw/capitalization_test.go	Three test functions to enforce capitalization consistency across commands

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-12T14:54:26Z

docs/CAPITALIZATION_GUIDELINES.md

+# Capitalization Guidelines for gh-aw CLI
+
+This document defines the capitalization rules for the gh-aw CLI to ensure consistency across all command descriptions and documentation.


This documentation file is located in the wrong directory. According to the custom coding guidelines, Astro Starlight documentation should be in docs/src/content/docs/. The current location docs/CAPITALIZATION_GUIDELINES.md is outside the Astro content structure and won't be integrated into the documentation site. Move this file to docs/src/content/docs/reference/capitalization.md (or similar path) and add proper frontmatter with title and description fields.

See below for a potential fix:

@ -1,3 +1,8 @@ --- title: Capitalization Guidelines description: Rules and examples for consistent capitalization in gh-aw CLI command descriptions and documentation. ---

Fixed in commit 9b52bb6. Moved documentation to docs/src/content/docs/reference/capitalization.md with proper Astro Starlight frontmatter (title, description, sidebar order).

Copilot · 2025-11-12T14:54:26Z

docs/CAPITALIZATION_GUIDELINES.md

+## Decision: Option 2 - Context-Based Capitalization
+
+The gh-aw CLI follows **Option 2** for capitalization:
+
+### Rules


This documentation doesn't follow the Diátaxis framework specified in the custom coding guidelines. This content is 'Explanation' type (understanding-oriented) explaining 'why things are the way they are' and design decisions. However, it mixes in elements of Reference (the rules) and lacks proper structure. Consider restructuring: use indicative mood ('This approach provides', 'The tool uses'), discuss design tradeoffs, and separate the reference-style rules into a proper reference section or table.

Fixed in commit 9b52bb6. Restructured as Explanation-oriented content following Diátaxis framework - uses indicative mood, discusses design tradeoffs, and provides historical context.

Copilot · 2025-11-12T14:54:27Z

cmd/gh-aw/capitalization_test.go

+
+		// Check if uppercase was used without "GitHub" prefix (which would be wrong)
+		if strings.Contains(cmd.Short, "Agentic Workflow") && !strings.Contains(cmd.Short, "GitHub Agentic Workflow") {
+			t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Short", cmd.Name())
+		}
+		if strings.Contains(cmd.Long, "Agentic Workflow") && !strings.Contains(cmd.Long, "GitHub Agentic Workflow") {
+			t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Long", cmd.Name())
+		}


Lines 66-71 are unreachable code. The logic flow at lines 52-63 already handles all cases: if a command mentions 'agentic workflow' (case-insensitive check at line 54), it either finds lowercase usage and continues (line 60-62), or falls through to line 65. However, the only way to reach line 66 is if the command mentions 'agentic workflow' but doesn't have lowercase 'agentic workflow', which means it must have capitalized it. But line 60 already continues if lowercase is found, and line 54-56 continues if not mentioned at all. The checks at lines 66-71 will never execute because any command that reaches them would have already continued at line 62.

Suggested change

// Check if uppercase was used without "GitHub" prefix (which would be wrong)

if strings.Contains(cmd.Short, "Agentic Workflow") && !strings.Contains(cmd.Short, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Short", cmd.Name())

}

if strings.Contains(cmd.Long, "Agentic Workflow") && !strings.Contains(cmd.Long, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Long", cmd.Name())

}

Fixed in commit 9b52bb6. Removed unreachable code (lines 66-71) by simplifying the test logic.

Copilot · 2025-11-12T14:54:27Z

cmd/gh-aw/capitalization_test.go

+	if !strings.Contains(versionCmd.Long, "GitHub Agentic Workflows") && !strings.Contains(versionCmd.Short, "GitHub Agentic Workflows") {
+		// Version command is allowed to not have the product name in descriptions
+		// since it's output in the Run function instead
+	}


This if statement with only a comment in the body serves no purpose and adds confusion. If the version command is explicitly allowed to not have the product name, either remove this check entirely or add an explicit skip comment before checking other commands. The current code suggests a check is happening when it's actually just documentation.

Suggested change

if !strings.Contains(versionCmd.Long, "GitHub Agentic Workflows") && !strings.Contains(versionCmd.Short, "GitHub Agentic Workflows") {

// Version command is allowed to not have the product name in descriptions

// since it's output in the Run function instead

}

// Version command is allowed to not have the product name in descriptions,

// since it's output in the Run function instead.

Fixed in commit 9b52bb6. Removed the empty if block and replaced with a comment explaining why version command is skipped.

Copilot · 2025-11-12T14:54:27Z

cmd/gh-aw/capitalization_test.go

+		// Verify they use lowercase "agentic workflows" or "agentic workflow" somewhere
+		lowerShort := strings.ToLower(cmd.Short)
+		lowerLong := strings.ToLower(cmd.Long)
+		if !strings.Contains(lowerShort, "agentic workflow") && !strings.Contains(lowerLong, "agentic workflow") {
+			// Not all commands need to mention agentic workflows
+			continue
+		}
+
+		// If they mention it, ensure it's lowercase
+		if strings.Contains(cmd.Short, "agentic workflow") || strings.Contains(cmd.Long, "agentic workflow") {
+			// Lowercase usage found - this is correct
+			continue
+		}
+
+		// Check if uppercase was used without "GitHub" prefix (which would be wrong)
+		if strings.Contains(cmd.Short, "Agentic Workflow") && !strings.Contains(cmd.Short, "GitHub Agentic Workflow") {
+			t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Short", cmd.Name())
+		}
+		if strings.Contains(cmd.Long, "Agentic Workflow") && !strings.Contains(cmd.Long, "GitHub Agentic Workflow") {
+			t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Long", cmd.Name())


The test logic from lines 51-71 is overly complex and contains unreachable code. Simplify by checking directly: if the command contains 'Agentic Workflow' (without 'GitHub' prefix), it's wrong and should error. The current multi-step approach with lowercase conversion and multiple continues makes the logic harder to follow and contains dead code (lines 66-71).

Suggested change

// Verify they use lowercase "agentic workflows" or "agentic workflow" somewhere

lowerShort := strings.ToLower(cmd.Short)

lowerLong := strings.ToLower(cmd.Long)

if !strings.Contains(lowerShort, "agentic workflow") && !strings.Contains(lowerLong, "agentic workflow") {

// Not all commands need to mention agentic workflows

continue

}

// If they mention it, ensure it's lowercase

if strings.Contains(cmd.Short, "agentic workflow") || strings.Contains(cmd.Long, "agentic workflow") {

// Lowercase usage found - this is correct

continue

}

// Check if uppercase was used without "GitHub" prefix (which would be wrong)

if strings.Contains(cmd.Short, "Agentic Workflow") && !strings.Contains(cmd.Short, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Short", cmd.Name())

}

if strings.Contains(cmd.Long, "Agentic Workflow") && !strings.Contains(cmd.Long, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' should use lowercase 'agentic workflow' not 'Agentic Workflow' in Long", cmd.Name())

// Directly check for incorrect usage of "Agentic Workflow" without "GitHub" prefix

if strings.Contains(cmd.Short, "Agentic Workflow") && !strings.Contains(cmd.Short, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' Short description should use lowercase 'agentic workflow' for generic usage, not 'Agentic Workflow'. Got: %s", cmd.Name(), cmd.Short)

}

if strings.Contains(cmd.Long, "Agentic Workflow") && !strings.Contains(cmd.Long, "GitHub Agentic Workflow") {

t.Errorf("Command '%s' Long description should use lowercase 'agentic workflow' for generic usage, not 'Agentic Workflow'. Got: %s", cmd.Name(), cmd.Long)

Fixed in commit 9b52bb6. Simplified test logic to directly check for incorrect usage of "Agentic Workflow" without "GitHub" prefix, removing all the overly complex logic and unreachable code.

pelikhan · 2025-11-12T14:55:32Z

@copilot lint

- Simplify test logic by removing unreachable code (lines 66-71) - Remove empty if block (lines 24-27) - Directly check for incorrect capitalization - Move documentation from docs/CAPITALIZATION_GUIDELINES.md to docs/src/content/docs/reference/capitalization.md - Follow Diátaxis framework (Explanation-oriented) - Add proper frontmatter with title, description, sidebar order - All linting and tests pass Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-11-12T15:04:14Z

@copilot lint

Linting completed successfully. All issues resolved in commit 9b52bb6.

pelikhan · 2025-11-12T18:09:30Z

docs/src/content/docs/reference/capitalization.md

+  order: 900
+---
+
+The gh-aw CLI follows context-based capitalization to distinguish between the product name and generic workflow references. This approach provides clarity and maintains professional consistency across all user-facing text.


@copilot move to specs folder

Initial plan

69d3c0a

Copilot AI assigned Copilot and pelikhan Nov 12, 2025

Copilot started work on behalf of pelikhan November 12, 2025 14:37 View session

Copilot AI and others added 2 commits November 12, 2025 14:48

Add capitalization tests and documentation

923b63f

- Add comprehensive tests in cmd/gh-aw/capitalization_test.go - Create CAPITALIZATION_GUIDELINES.md documentation - Verify existing code already follows Option 2 correctly Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Apply go fmt to capitalization_test.go

5bce622

pelikhan approved these changes Nov 12, 2025

View reviewed changes

pelikhan marked this pull request as ready for review November 12, 2025 14:50

Copilot AI review requested due to automatic review settings November 12, 2025 14:50

Copilot started reviewing on behalf of pelikhan November 12, 2025 14:51 View session

Copilot finished reviewing on behalf of pelikhan November 12, 2025 14:52

Copilot AI changed the title ~~[WIP] Fix inconsistent capitalization of 'agentic workflows'~~ Add capitalization consistency tests and documentation Nov 12, 2025

Copilot AI requested a review from pelikhan November 12, 2025 14:53

Copilot finished work on behalf of pelikhan November 12, 2025 14:53

Copilot AI reviewed Nov 12, 2025

View reviewed changes

Copilot started work on behalf of pelikhan November 12, 2025 14:56 View session

Copilot finished work on behalf of pelikhan November 12, 2025 15:06

pelikhan reviewed Nov 12, 2025

View reviewed changes

Copilot started work on behalf of pelikhan November 12, 2025 18:10 View session

pelikhan merged commit 3a24f3c into main Nov 12, 2025
39 of 40 checks passed

pelikhan deleted the copilot/fix-capitalization-in-command-descriptions branch November 12, 2025 18:15

Copilot finished work on behalf of pelikhan November 12, 2025 18:15

Copilot AI requested a review from pelikhan November 12, 2025 18:15

		# Capitalization Guidelines for gh-aw CLI

		This document defines the capitalization rules for the gh-aw CLI to ensure consistency across all command descriptions and documentation.

Conversation

Copilot AI commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fix CLI Capitalization Consistency ✅

Summary

Changes

1. Automated Tests (cmd/gh-aw/capitalization_test.go)

2. Documentation (docs/src/content/docs/reference/capitalization.md)

Addressed PR Feedback

Verification

Product Name (Capitalized) ✅

Generic Usage (Lowercase) ✅

Technical Terms (Capitalized) ✅

Test Results

Current State

Examples of Inconsistency

Issue

Recommendation

Suggested Approach

Files Affected

Impact

Comments on the Issue (you are @copilot in this section)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Nov 12, 2025

Uh oh!

Copilot AI commented Nov 12, 2025

Uh oh!

pelikhan Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Nov 12, 2025 •

edited

Loading

1. Automated Tests (`cmd/gh-aw/capitalization_test.go`)

2. Documentation (`docs/src/content/docs/reference/capitalization.md`)