Rename /refactor to /modify, start running the app, and update GEMINI.md (#69)

Author: gspencergoog

.gemini/GEMINI.md

@@ -1,10 +1,10 @@
 # Project Overview
 
-This repository contains a Gemini CLI extension for facilitating Flutter and Dart development. The extension provides a set of commands to streamline common development tasks, including project creation, refactoring, and committing code. It enforces a set of coding standards and best practices for building high-quality Flutter and Dart applications.
+This repository contains a Gemini CLI extension for facilitating Flutter and Dart development. The extension provides a set of commands to streamline common development tasks, including project creation, modification, and committing code. It enforces a set of coding standards and best practices for building high-quality Flutter and Dart applications.
 
 The core of this extension is the `flutter.md` context file, which provides a comprehensive set of rules and guidelines for the AI model. These guidelines cover everything from project structure and coding style to state management and testing.
 
-The extension also includes a set of commands defined in `.toml` files within the `commands` directory. These commands provide a structured way to interact with the AI model for tasks such as creating new apps, refactoring existing code, and preparing changes for commit.
+The extension also includes a set of commands defined in `.toml` files within the `commands` directory. These commands provide a structured way to interact with the AI model for tasks such as creating new apps, modifying existing code, and preparing changes for commit.
 
 ## Building and Running
 

README.md

@@ -7,7 +7,7 @@ Help Gemini CLI create, build, test, and run Flutter apps.
 ## ✨ Features
 
 - **🚀 Project Bootstrapping**: Create new Flutter projects from scratch with built-in best practices, including linters, documentation, and design planning.
-- **🔧 Guided Refactoring**: Execute complex refactoring tasks with automated planning, git branch management, and step-by-step implementation guides for your approval.
+- **🔧 Guided Modifications**: Execute complex modification tasks with automated planning, git branch management, and step-by-step implementation guides for your approval.
 - **✅ Automated Pre-Commit Checks**: Automatically format, analyze, and test your code before committing to maintain codebase quality.
 - **✍️ Smart Commit Messaging**: Generate descriptive, conventional commit messages based on your staged changes.
 - **🧠 Context Priming**: Initializes Gemini with specific rules and context for Dart and Flutter, ensuring high-quality, idiomatic code generation.
@@ -46,7 +46,7 @@ The new commands will be available in new Gemini CLI sessions. The following com
 
 - `/create-app` - Guides you through bootstrapping a new Flutter project with best practices.
 - `/create-package` - Guides you through bootstrapping a new Dart package with best practices.
-- `/refactor` - Manages a structured refactoring session with automated planning.
+- `/modify` - Manages a structured modification session with automated planning.
 - `/commit` - Automates pre-commit checks and generates a descriptive commit message.
 
 ## 💡 Usage
@@ -68,19 +68,19 @@ Initiates a guided process to bootstrap a new Flutter application, ensuring your
 /create-app I want to create a trip planning app
 ```
 
-### `/refactor`
+### `/modify`
 
-Starts a structured session to refactor existing code. It helps you plan and execute changes safely and efficiently.
+Starts a structured session to modify existing code. It helps you plan and execute changes safely and efficiently.
 
 **Process:**
 
-1.  Asks for your high-level refactoring goals and what you want to accomplish.
-2.  Offers to create a new `git` branch for the refactoring work, isolating changes.
-3.  Generates a `REFACTOR.md` design document detailing the proposed changes.
-4.  Creates a phased `REFACTOR_IMPLEMENTATION.md` plan for your review and approval.
+1.  Asks for your high-level modification goals and what you want to accomplish.
+2.  Offers to create a new `git` branch for the modification work, isolating changes.
+3.  Generates a `MODIFICATION_DESIGN.md` design document detailing the proposed changes.
+4.  Creates a phased `MODIFICATION_IMPLEMENTATION.md` plan for your review and approval.
 
 ```bash
-/refactor
+/modify
 ```
 
 ### `/commit`

commands/create-app.toml

@@ -47,6 +47,8 @@ The design doc should (at least) include sections for:
 - A summary of the design
 - References to research URLs used to arrive at the design.
 
+Be sure to **actually fetch and read** the research URLs **before** writing the design document. Do actual web research on the topics that are important to the design.
+
 You must ask the user to review this design document and they must approve it before you continue on to create the implementation plan. They must review and approve it first because if they ask for any changes, it may affect the implementation plan.
 
 ## Implementation plan
@@ -70,20 +72,26 @@ In the first phase of the implementation plan, include:
 - [ ] Update the README.md to include a short placeholder description of the package.
 - [ ] Create the CHANGELOG.md to have the initial version of 0.1.0.
 - [ ] Commit this empty version of the package to either a new branch or the current branch based on the user's preference.
+- [ ] After commiting the change, start running the app with the launch_app tool on the user's preferred device.
 
 The implementation plan should specify after each phase that you should:
 
 - [ ] Create/modify unit tests for testing the code added or modified in this phase, if relevant.
-- [ ] Run the dart_fix and dart_format tools to clean up the code.
+- [ ] Run the dart_fix tool to clean up the code.
 - [ ] Run the analyze_files tool one more time and fix any issues.
 - [ ] Run any tests to make sure they all pass.
-- [ ] Run dart_format one more time to make sure that the formatting is still correct if you made any changes during the analysis and testing steps.
+- [ ] Run dart_format to make sure that the formatting is correct.
 - [ ] Re-read the IMPLEMENTATION.md file to see what, if anything, has changed in the implementation plan, and if it has changed, take care of anything the changes imply.
 - [ ] Update the IMPLEMENTATION.md file with the current state, including any learnings, surprises, or deviations in the Journal section. Check off any checkboxes of items that have been completed.
 - [ ] Use `git diff` to verify the changes that have been made, and create a suitable commit message for any changes, following any guidelines you have about commit messages. Be sure to properly escape dollar signs and backticks, and present the change message to the user for approval.
 - [ ] Wait for approval. Don't commit the changes or move on to the next phase of implementation until the user approves the commit.
+- [ ] After commiting the change, if the app is running, use the hot_reload tool to reload it.
+
+In the last phase of the plan, include steps to:
 
-In the last phase of the plan, include a step to create a comprehensive README.md file for the package.
+- [ ] Create a comprehensive README.md file for the package.
+- [ ] Create a GEMINI.md file in the project directory that describes the app, its purpose, and implementation details of the application and the layout of the files.
+- [ ] Ask the user to inspect the app and the code and say if they are satisfied with it, or if any modifications are needed.
 
 You must ask the user to review this implementation plan and they must approve it before starting implementation. They must review and approve it before you begin because if they ask for any changes, the changes may affect the implementation.
 

commands/create-package.toml

@@ -4,7 +4,7 @@
 
 # This command will be invoked via: /flutter:create-package
 
-description = "Create a new Dart or Flutter package."
+description = "Create a new Dart or Flutter package, with an opinionated structure."
 
 prompt = """
 We're going to build a new Dart or Flutter package.
@@ -48,6 +48,8 @@ The design doc should (at least) include sections for:
 - A summary of the design
 - References to research URLs used to arrive at the design.
 
+Be sure to **actually fetch and read** the research URLs **before** writing the design document. Do actual web research on the topics that are important to the design.
+
 You must ask the user to review this design document and they must approve it before you continue on to create the implementation plan. They must review and approve it first because if they ask for any changes, it may affect the implementation plan.
 
 ## Implementation plan
@@ -75,16 +77,20 @@ In the first phase of the implementation plan, include:
 The implementation plan should specify after each phase that you should:
 
 - [ ] Create/modify unit tests for testing the code added or modified in this phase, if relevant.
-- [ ] Run the dart_fix and dart_format tools to clean up the code.
+- [ ] Run the dart_fix tool to clean up the code.
 - [ ] Run the analyze_files tool one more time and fix any issues.
 - [ ] Run any tests to make sure they all pass.
-- [ ] Run dart_format one more time to make sure that the formatting is still correct if you made any changes during the analysis and testing steps.
+- [ ] Run dart_format to make sure that the formatting is correct.
 - [ ] Re-read the IMPLEMENTATION.md file to see what, if anything, has changed in the implementation plan, and if it has changed, take care of anything the changes imply.
 - [ ] Update the IMPLEMENTATION.md file with the current state, including any learnings, surprises, or deviations in the Journal section. Check off any checkboxes of items that have been completed.
 - [ ] Use `git diff` to verify the changes that have been made, and create a suitable commit message for any changes, following any guidelines you have about commit messages. Be sure to properly escape dollar signs and backticks, and present the change message to the user for approval.
 - [ ] Wait for approval. Don't commit the changes or move on to the next phase of implementation until the user approves the commit.
 
-In the last phase of the plan, include a step to create a comprehensive README.md file for the package.
+In the last phase of the plan, include steps to:
+
+- [ ] Create a comprehensive README.md file for the package.
+- [ ] Create a GEMINI.md file in the project directory that describes the package, its purpose, and implementation details of the package and the layout of the files.
+- [ ] Ask the user to inspect the package and say if they are satisfied with it, or if any modifications are needed.
 
 You must ask the user to review this implementation plan and they must approve it before starting implementation. They must review and approve it before you begin because if they ask for any changes, the changes may affect the implementation.
 

commands/modify.toml

@@ -0,0 +1,88 @@
+# Copyright 2025 The Flutter Authors.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+# This command will be invoked via: /flutter:modify
+
+description = "Perform a modification of your Flutter or Dart project."
+
+prompt = """
+We're going to modify some code.
+
+## Problem specification
+
+First, prompt the user for a description of what the purpose and details of the modification will be.
+
+Once the user has specified the description and purpose of the modification, outline the information that you will be collecting before creating the design and implementation plan, and present the list to the user, along with your first question.
+
+## Collecting Information
+
+Next, collect remaining information from the user, one question at a time.
+
+The information you need to collect includes, but might not be limited to:
+
+- If there are ambiguous elements to the modification, ask the user questions to clarify. When the goal is clear, or the user says to, then move on.
+- Whether to do the work on the current git branch, or a new feature branch.
+  - Suggest a branch name, making sure it is a valid git branch name.
+
+## Initialize workspace
+
+First, make sure there are no uncommitted changes on the current branch. If there are, notify the user and ask what they would like to do about them before proceeding.
+
+If the user wants the work done on a new branch, create the branch now.
+
+## Modification design document
+
+Develop a **DETAILED** Markdown-formatted design document that follows all of the guidance you have about Dart and Flutter design patterns, rules, best practices, and core principles. Save the design document in MODIFICATION_DESIGN.md in the top directory of the workspace. Feel free to use your available tools to research any aspects of the modification that are unclear.
+
+The design doc should (at least) include:
+
+- An overview
+- A detailed analysis of the goal or problem
+- Alternatives considered
+- A detailed design for the modification
+- Any diagrams needed to explain the modification or the design, in Mermaid format.
+  - Be sure to put quotes around labels that include special characters (e.g. parenthesis).
+- A summary of the design
+- References to research URLs used to arrive at the design.
+
+Be sure to **actually fetch and read** the research URLs **before** writing the design document. Do actual web research on the topics that are important to the design.
+
+You must ask the user to review this design document and they must approve it before you continue on to create the implementation plan. They must review and approve it first because if they ask for any changes, it may affect the implementation plan.
+
+## Implementation plan
+
+After getting explicit approval from the user for the MODIFICATION_DESIGN.md document, develop a **DETAILED** Markdown-formatted phased implementation plan of checkboxed tasks that need to be performed in order to finish the modification. Save the implementation plan in MODIFICATION_IMPLEMENTATION.md in the top of the repo.
+
+The implementation plan should include a section for a "Journal" which will be updated after each phase and contain a log of the actions taken, things learned, surprises, and deviations from the plan. It should be in chronological order.
+
+The plan should include instructions similar to: "After completing a task, if you added any TODOs to the code or didn't fully implement anything, make sure to add new tasks so that you can come back and complete them later." to prevent leaving tasks unfinished.
+
+In the first phase of the implementation plan, include:
+- [ ] Run all tests to ensure the project is in a good state before starting modifications.
+
+The implementation plan should specify after each phase that you should:
+
+- [ ] Create/modify unit tests for testing the code added or modified in this phase, if relevant.
+- [ ] Run the dart_fix tool to clean up the code.
+- [ ] Run the analyze_files tool one more time and fix any issues.
+- [ ] Run any tests to make sure they all pass.
+- [ ] Run dart_format to make sure that the formatting is correct.
+- [ ] Re-read the MODIFICATION_IMPLEMENTATION.md file to see what, if anything, has changed in the implementation plan, and if it has changed, take care of anything the changes imply.
+- [ ] Update the MODIFICATION_IMPLEMENTATION.md file with the current state, including any learnings, surprises, or deviations in the Journal section. Check off any checkboxes of items that have been completed.
+- [ ] Use `git diff` to verify the changes that have been made, and create a suitable commit message for any changes, following any guidelines you have about commit messages. Be sure to properly escape dollar signs and backticks, and present the change message to the user for approval.
+- [ ] Wait for approval. Don't commit the changes or move on to the next phase of implementation until the user approves the commit.
+- [ ] After commiting the change, if an app is running, use the hot_reload tool to reload it.
+
+In the last phase of the plan, include steps to:
+
+- [ ] Update any README.md file for the package with relevant information from the modification (if any).
+- [ ] Update any GEMINI.md file in the project directory so that it still correctly describes the app, its purpose, and implementation details and the layout of the files.
+- [ ] Ask the user to inspect the package (and running app, if any) and say if they are satisfied with it, or if any modifications are needed.
+
+You must ask the user to review this implementation plan and they must approve it before starting implementation. They must review and approve it before you begin because if they ask for any changes, the changes may affect the implementation.
+
+## Implementation
+
+After getting explicit approval from the user for the MODIFICATION_IMPLEMENTATION.md document, begin implementing the plan.
+"""