docs: add helper command guidelines and anti-patterns

[jpoehnelt]

Summary

Documents guidelines for when helper commands (+verb) are justified vs. when they should be rejected. Adds anti-patterns with real PR examples (#563, #597) and flag design rules.

Changes

• AGENTS.md — Short helper guidelines section with key rule and link to full docs
• src/helpers/README.md — Exhaustive guidelines: anti-patterns, flag design rules, decision checklist, architecture reference, new helper checklist
• .gemini/style_guide.md — Link to helper guidelines for code review context

Motivation

External PRs have been submitted that either wrap single API calls already available via Discovery (#563) or add unbounded flags to expose API response data (#597). These conflict with the schema-driven design philosophy.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 99b4f8b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request aims to standardize the development and review process for helper commands within the gws CLI. By documenting clear guidelines, anti-patterns, and flag design rules, it ensures that new helpers align with the project's schema-driven philosophy, preventing the introduction of redundant or overly complex commands that could otherwise be handled by existing Discovery-based functionality or post-processing tools.

Highlights

• New Helper Command Guidelines in AGENTS.md: Introduced a new section in AGENTS.md outlining the purpose of helper commands (+verb) and providing an important warning against common anti-patterns, along with a link to more detailed documentation.
• Comprehensive Helper Command Documentation: Completely revamped src/helpers/README.md to establish exhaustive guidelines for helper commands, including design principles, justifications, detailed anti-patterns with real-world examples, clear flag design rules, and a checklist for adding new helpers.

Ignored Files

• Ignored by pattern: .gemini/** (1)
  • .gemini/style_guide.md

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces excellent documentation for helper commands, including guidelines, anti-patterns, and checklists. This will greatly improve contributor experience and code quality. I've found one issue in the documentation where the Helper trait's handle method signature is incorrect in the code example, which could lead to confusion and compilation errors for developers. A comment has been added to address this.

[gemini-code-assist]

Code Review

This pull request introduces excellent and much-needed documentation detailing the guidelines and anti-patterns for creating helper commands. The new sections in AGENTS.md and the comprehensive src/helpers/README.md will be very valuable for contributors. However, the PR also includes stylistic reformatting of YAML frontmatter across a large number of SKILL.md files. While this improves readability, it expands the scope of the PR beyond its primary documentation goal. I've added a comment regarding this scope creep.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request significantly improves the documentation for helper commands by adding detailed guidelines, anti-patterns, and checklists in src/helpers/README.md and a summary in AGENTS.md. The changes are well-structured and provide valuable context for contributors. My review focuses on ensuring the accuracy and consistency of the new documentation. I've pointed out a potential discrepancy in the Helper trait signature documented in src/helpers/README.md which may not align with the current codebase, and an inconsistency in the documented path for the validate_resource_name function between AGENTS.md and src/helpers/README.md. Addressing these points will ensure the documentation is clear and accurate for developers.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces comprehensive guidelines for creating helper commands, clarifying when they are appropriate and what anti-patterns to avoid. The changes include a detailed README.md in the src/helpers directory and a summary in AGENTS.md. The documentation is well-structured and provides clear rules for contributors. I've found one issue with an incorrect code path in the new documentation.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request significantly improves the documentation by adding clear guidelines and anti-patterns for creating helper commands. The new src/helpers/README.md is comprehensive and will be a great resource for contributors. I have one point of feedback regarding an inconsistency in AGENTS.md.