feat: add configurable agent guidance filename with smart merge

[eliasecchig]

Summary

• Add --agent-guidance-filename CLI flag to create and enhance commands (default: GEMINI.md)
• Support custom filenames like CLAUDE.md or AGENTS.md for agent guidance files
• Smart merge during enhance: ASP-managed sections are updated while user content is preserved
• Persist agent_guidance_filename in project config (only when non-default) across all templates (Python, Go, TypeScript, Java)

Problem

Agent guidance files were hardcoded to GEMINI.md. Users of other coding agents (Claude Code, Cursor, etc.) had no way to generate guidance as CLAUDE.md or AGENTS.md. Additionally, enhance would overwrite the entire guidance file, losing any user-added content.

Solution

• Template filenames use {{cookiecutter.agent_guidance_filename}} instead of hardcoded GEMINI.md
• Guidance file content is wrapped in <!-- ASP-MANAGED-START/END: agent-guidance --> markers
• merge_guidance_file() replaces only the ASP-managed section, preserving user notes outside markers
• Non-default filename is persisted in create_params so enhance auto-detects it from saved config
• CLI override passes through agent_guidance_filename to the subprocess re-invocation in enhance

[gemini-code-assist]

Summary of Changes

Hello @eliasecchig, 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 significantly enhances the flexibility and user experience of the Agent Starter Pack by allowing users to customize the filename for agent guidance documentation. Previously, this was fixed to GEMINI.md, which was restrictive for users of other agent platforms. Furthermore, it introduces a robust smart merge capability for these guidance files, ensuring that any custom notes or modifications made by the user are preserved during project enhancement operations, addressing a critical data loss concern.

Highlights

• Configurable Agent Guidance Filename: Introduced a new --agent-guidance-filename CLI flag for create and enhance commands, allowing users to specify custom filenames for agent guidance (e.g., CLAUDE.md, AGENTS.md) instead of the hardcoded GEMINI.md.
• Smart Merge for Guidance Files: Implemented a 'smart merge' mechanism for agent guidance files during the enhance operation. This preserves user-added content outside of designated ASP-managed sections, preventing accidental overwrites.
• Persistence of Configuration: Ensured that the custom agent_guidance_filename is persisted in the project's configuration (e.g., .asp.toml, pom.xml, pyproject.toml) when it deviates from the default, allowing enhance to automatically detect and use it.
• Templated Guidance Files: Updated base templates across Python, Go, Java, and TypeScript to use {{cookiecutter.agent_guidance_filename}} for guidance file names and wrapped the generated content with <!-- ASP-MANAGED-START/END: agent-guidance --> markers to facilitate smart merging.
• New merge_guidance_file Utility: Added a new utility function merge_guidance_file responsible for intelligently combining new template content with existing guidance files, respecting user modifications.

Changelog

• agent_starter_pack/base_templates/go/.asp.toml
  • Updated to conditionally include the agent_guidance_filename in the project configuration.
• agent_starter_pack/base_templates/go/GEMINI.md
  • Removed the hardcoded GEMINI.md file.
• agent_starter_pack/base_templates/go/{{cookiecutter.agent_guidance_filename}}
  • Added a new templated agent guidance file, dynamically named, including ASP-managed markers.
• agent_starter_pack/base_templates/java/GEMINI.md
  • Removed the hardcoded GEMINI.md file.
• agent_starter_pack/base_templates/java/pom.xml
  • Updated to conditionally include the asp.agent_guidance_filename property in the Maven pom.xml.
• agent_starter_pack/base_templates/java/{{cookiecutter.agent_guidance_filename}}
  • Added a new templated agent guidance file, dynamically named, including ASP-managed markers.
• agent_starter_pack/base_templates/python/GEMINI.md
  • Renamed the GEMINI.md file to use the templated {{cookiecutter.agent_guidance_filename}} and updated its content with ASP-managed markers.
• agent_starter_pack/base_templates/python/pyproject.toml
  • Updated to conditionally include the agent_guidance_filename in the project configuration.
• agent_starter_pack/base_templates/typescript/.asp.toml
  • Updated to conditionally include the agent_guidance_filename in the project configuration.
• agent_starter_pack/cli/commands/create.py
  • Added the --agent-guidance-filename CLI option with a default of GEMINI.md.
  • Modified the create function signature to accept agent_guidance_filename.
  • Passed the agent_guidance_filename to the process_template function.
• agent_starter_pack/cli/commands/enhance.py
  • Modified the enhance function signature to accept agent_guidance_filename.
  • Added logic to include agent_guidance_filename in cli_override_args if it's not the default.
  • Passed the agent_guidance_filename to the process_template function during enhancement.
• agent_starter_pack/cli/utils/template.py
  • Added a new function merge_guidance_file to intelligently merge ASP-managed sections of guidance files while preserving user content.
  • Modified the process_template function to accept agent_guidance_filename.
  • Updated process_template to pass agent_guidance_filename to the cookiecutter context.
  • Implemented logic in process_template to skip the guidance file during standard copying and instead merge it using merge_guidance_file if in enhance mode.
• tests/cli/utils/test_template.py
  • Imported the new merge_guidance_file function for testing.
  • Added a new test class TestMergeGuidanceFile with multiple test cases covering creation, prepending, replacement, custom filenames, and preservation of content before and after ASP sections.

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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

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

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for configurable agent guidance filenames and a smart merge capability to preserve user customizations during enhance. The changes are well-implemented across templates, CLI commands, and utility functions. The inclusion of comprehensive tests for the new merge logic is commendable. I have one suggestion to further improve the robustness of the merge function. Overall, this is a great enhancement to the tool.