From c2df610d2edaca1787d8eb9bec242566feb34044 Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Thu, 9 Oct 2025 07:21:29 +0500 Subject: [PATCH 1/5] feat: Add version detection warnings for hot reload Add warnings in all commands that use hot_reload to inform users about the known limitation on Flutter stable <= 3.37.0. This helps users understand why hot reload may fail and provides clear guidance on workarounds (switching to Flutter main channel or manually restarting the app). Changes: - Updated /debug-app command to check Flutter version early and warn users about hot reload limitations - Added inline warnings in /create-app and /modify commands when hot_reload is used - Updated CHANGELOG.md to document this improvement Related to gemini-cli-extensions/flutter#15 --- CHANGELOG.md | 7 +++++++ commands/create-app.toml | 1 + commands/debug-app.toml | 11 ++++++++++- commands/modify.toml | 1 + 4 files changed, 19 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e8888c..07e4890 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,10 @@ +## Unreleased + +- Added version detection warnings for hot reload on Flutter stable ≤ 3.37.0 + - Updated `/debug-app`, `/create-app`, and `/modify` commands to warn users about hot reload limitations + - Provides guidance to switch to Flutter main channel or manually restart apps when hot reload fails + - Related to [#15](https://github.com/gemini-cli-extensions/flutter/issues/15) + ## 0.3.0 - Removed the `flutter_launcher` MCP server because it has been integrated into diff --git a/commands/create-app.toml b/commands/create-app.toml index 94ae571..857684f 100644 --- a/commands/create-app.toml +++ b/commands/create-app.toml @@ -86,6 +86,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. + - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. In the last phase of the plan, include steps to: diff --git a/commands/debug-app.toml b/commands/debug-app.toml index 01a96a3..3b06b9e 100644 --- a/commands/debug-app.toml +++ b/commands/debug-app.toml @@ -34,6 +34,13 @@ Next, collect additional information required for debugging. Ask the user one qu Before diving into the code, let's verify the project's dependencies and environment. - [ ] Run `flutter doctor` to get the Flutter and Dart SDK versions and check for any issues reported. +- [ ] Check the Flutter version output and determine if hot reload is supported: + - **IMPORTANT**: Hot reload through the Dart MCP server does not work reliably on Flutter stable ≤ 3.37.0 (see [issue #15](https://github.com/gemini-cli-extensions/flutter/issues/15)) + - If the user is on Flutter stable ≤ 3.37.0, warn them that hot reload may fail during this debugging session + - Suggest they either: + 1. Switch to Flutter main/master channel for full hot reload support, OR + 2. Manually restart the app after making code changes instead of using hot_reload + - If they choose to proceed with stable, acknowledge their choice and remind them about the limitation when using hot_reload later - [ ] Use the `pub` tool with the `outdated` command to look for outdated packages or dependency conflicts in `pubspec.yaml` and `pubspec.lock`. - Run the command `pub` tool with `upgrade` to upgrade to latest versions. - If that isn't sufficient, sometimes upgrading the package version to a new major version can help. The `pub` tool can't do this, so run the command `dart pub upgrade --major-versions` to do this. @@ -62,7 +69,9 @@ The debugging strategy should be chosen to yield the best results and may involv - **Logging and Tracing:** - Add strategic logging statements to the code to trace execution flow. Prefer `debugPrint()` over `print()` for cleaner, non-interfering output. - - Use `hot_reload` to apply logging changes quickly while preserving the app's state. If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. + - Use `hot_reload` to apply logging changes quickly while preserving the app's state. + - **Note**: If the user is on Flutter stable ≤ 3.37.0 and hot_reload fails, suggest they manually restart the app or switch to Flutter main channel + - If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. - **Flutter DevTools & UI Inspection:** - **For UI and layout bugs:** Use the `get_widget_tree` tool to inspect the widget hierarchy and properties. diff --git a/commands/modify.toml b/commands/modify.toml index 8d93f10..56f5843 100644 --- a/commands/modify.toml +++ b/commands/modify.toml @@ -73,6 +73,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. + - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. In the last phase of the plan, include steps to: From 61989493085bd3470344517a5602b0f935fbddae Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Tue, 6 Jan 2026 08:17:30 +0500 Subject: [PATCH 2/5] Address review feedback for hot reload version warnings - Simplify verbose checklist in debug-app.toml to a single note - Remove issue #15 reference per reviewer request - Use "main" channel consistently (not "main/master") - Reword from "does not work" to "only works reliably" - Change "restarting" to "reloading" for accuracy --- commands/create-app.toml | 2 +- commands/debug-app.toml | 10 ++-------- commands/modify.toml | 2 +- 3 files changed, 4 insertions(+), 10 deletions(-) diff --git a/commands/create-app.toml b/commands/create-app.toml index 857684f..c18beb3 100644 --- a/commands/create-app.toml +++ b/commands/create-app.toml @@ -86,7 +86,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. - - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. + - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. In the last phase of the plan, include steps to: diff --git a/commands/debug-app.toml b/commands/debug-app.toml index 3b06b9e..d8873b3 100644 --- a/commands/debug-app.toml +++ b/commands/debug-app.toml @@ -34,13 +34,7 @@ Next, collect additional information required for debugging. Ask the user one qu Before diving into the code, let's verify the project's dependencies and environment. - [ ] Run `flutter doctor` to get the Flutter and Dart SDK versions and check for any issues reported. -- [ ] Check the Flutter version output and determine if hot reload is supported: - - **IMPORTANT**: Hot reload through the Dart MCP server does not work reliably on Flutter stable ≤ 3.37.0 (see [issue #15](https://github.com/gemini-cli-extensions/flutter/issues/15)) - - If the user is on Flutter stable ≤ 3.37.0, warn them that hot reload may fail during this debugging session - - Suggest they either: - 1. Switch to Flutter main/master channel for full hot reload support, OR - 2. Manually restart the app after making code changes instead of using hot_reload - - If they choose to proceed with stable, acknowledge their choice and remind them about the limitation when using hot_reload later + - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. - [ ] Use the `pub` tool with the `outdated` command to look for outdated packages or dependency conflicts in `pubspec.yaml` and `pubspec.lock`. - Run the command `pub` tool with `upgrade` to upgrade to latest versions. - If that isn't sufficient, sometimes upgrading the package version to a new major version can help. The `pub` tool can't do this, so run the command `dart pub upgrade --major-versions` to do this. @@ -70,7 +64,7 @@ The debugging strategy should be chosen to yield the best results and may involv - **Logging and Tracing:** - Add strategic logging statements to the code to trace execution flow. Prefer `debugPrint()` over `print()` for cleaner, non-interfering output. - Use `hot_reload` to apply logging changes quickly while preserving the app's state. - - **Note**: If the user is on Flutter stable ≤ 3.37.0 and hot_reload fails, suggest they manually restart the app or switch to Flutter main channel + - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. - If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. - **Flutter DevTools & UI Inspection:** diff --git a/commands/modify.toml b/commands/modify.toml index 56f5843..0631860 100644 --- a/commands/modify.toml +++ b/commands/modify.toml @@ -73,7 +73,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. - - **Note**: Hot reload does not work reliably on Flutter stable ≤ 3.37.0. If hot_reload fails, inform the user and suggest either switching to Flutter main channel or manually restarting the app. + - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. In the last phase of the plan, include steps to: From 9258fa4ee53ba7f867146635e4264ef31dce18ef Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Tue, 6 Jan 2026 08:49:38 +0500 Subject: [PATCH 3/5] Add guidance for running apps when launch_app unavailable Addresses issue #8 by providing clear instructions to users when they ask to run their app but the launch_app tool is not available or fails. Users are directed to either use flutter run in a terminal or their IDE's Flutter extension. --- flutter.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/flutter.md b/flutter.md index e80a581..3dc3879 100644 --- a/flutter.md +++ b/flutter.md @@ -816,6 +816,13 @@ education levels, and learning styles. PLEASE. DON'T FORGET TO USE THE DART TOOLS. I BEG YOU. +- **Running Apps**: If the user asks to "run the app" or "start the app" and the + `launch_app` tool is not available or fails, provide clear guidance: + + > "To run your app, open a new terminal, cd into your project directory, and + > type `flutter run`. Or, open your IDE and use its Run features via the + > Flutter extension or plugin." + - **PREREQUISITES**: - Before calling tools which operate on the project, you must use the `create_project` tool to create a project if it doesn't already exist. From 6fe5a56319c00f385b2be91a0872cc9d4acd0463 Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Fri, 30 Jan 2026 23:14:50 +0500 Subject: [PATCH 4/5] feat: use directory structure that supports multiple features Restructure specs directory to support multiple features with numbered directories. Each feature now gets its own subdirectory (e.g., 001-my-app) containing separate files for spec, data model, plan, tasks, and requirements. Changes: - Split DESIGN.md into spec.md, data-model.md, and plan.md - Rename IMPLEMENTATION.md to tasks.md - Add checklists/requirements.md for tracking requirements - Use three-digit numbered prefixes for feature directories Closes #47 --- commands/create-app.toml | 51 +++++++++++++++++++++++++++--------- commands/create-package.toml | 49 ++++++++++++++++++++++++++-------- commands/modify.toml | 49 ++++++++++++++++++++++++++-------- 3 files changed, 115 insertions(+), 34 deletions(-) diff --git a/commands/create-app.toml b/commands/create-app.toml index c18beb3..c60083c 100644 --- a/commands/create-app.toml +++ b/commands/create-app.toml @@ -32,28 +32,54 @@ Then create the package directory, if it doesn't already exist. **VERY IMPORTANT**: Change directories to the package directory now so that future operations are relative to that directory. -## Design document +## Feature specification directory -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 specs/DESIGN.md in the package directory. Feel free to use your available tools to research any aspects of the design that need clarification. +Create a numbered feature directory under `specs/` to organize all specification documents. The directory should be named with a three-digit prefix followed by a kebab-case feature name (e.g., `specs/001-my-app-name/`). If other numbered directories already exist in `specs/`, use the next available number. -The design doc should (at least) include sections for: +## Design documents -- An overview +Develop **DETAILED** Markdown-formatted design documents that follow all of the guidance you have about Dart and Flutter design patterns, rules, best practices, and core principles. Feel free to use your available tools to research any aspects of the design that need clarification. + +Create the following files in the feature specification directory: + +### specs/NNN-feature-name/spec.md +The main specification document containing: +- An overview of the app - A detailed analysis of the goal or problem - Alternatives considered -- A detailed design for the new package +- A detailed design for the new app - Any diagrams needed to explain 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. +### specs/NNN-feature-name/data-model.md +A dedicated document for the data model containing: +- Entity definitions and relationships +- Database schema (if applicable) +- State management structure +- Data flow diagrams in Mermaid format + +### specs/NNN-feature-name/plan.md +A high-level plan document containing: +- Project milestones +- Key deliverables +- Dependencies and risks +- Success criteria + +### specs/NNN-feature-name/checklists/requirements.md +A requirements checklist containing: +- [ ] Functional requirements (checkboxed list) +- [ ] Non-functional requirements (checkboxed list) +- [ ] User stories or acceptance criteria + +Be sure to **actually fetch and read** the research URLs **before** writing the design documents. 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. +You must ask the user to review these design documents and they must approve them before you continue on to create the implementation plan. They must review and approve 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 DESIGN.md document, Develop a **DETAILED** Markdown-formatted phased implementation plan of checkboxed tasks that need to be performed in order to finish developing the package. Save the implementation plan in specs/IMPLEMENTATION.md in the package directory. +After getting explicit approval from the user for the design documents, develop a **DETAILED** Markdown-formatted phased implementation plan of checkboxed tasks that need to be performed in order to finish developing the app. Save the implementation plan in `specs/NNN-feature-name/tasks.md` (in the same feature directory as the design documents). 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. @@ -81,8 +107,9 @@ The implementation plan should specify after each phase that you should: - [ ] 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 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. +- [ ] Re-read the tasks.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 tasks.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. +- [ ] Update the checklists/requirements.md file to check off any requirements that have been satisfied. - [ ] 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. @@ -94,9 +121,9 @@ In the last phase of the plan, include steps to: - [ ] 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. +You must ask the user to review the tasks.md 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 IMPLEMENTATION.md document, begin implementing the plan. +After getting explicit approval from the user for the tasks.md document, begin implementing the plan. """ diff --git a/commands/create-package.toml b/commands/create-package.toml index 43eb218..58dd349 100644 --- a/commands/create-package.toml +++ b/commands/create-package.toml @@ -33,13 +33,19 @@ Then create the package directory, if it doesn't already exist. **VERY IMPORTANT**: Change directories to the package directory now so that future operations are relative to that directory. -## Design document +## Feature specification directory -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 specs/DESIGN.md in the package directory. Feel free to use your available tools to research any aspects of the design that need clarification. +Create a numbered feature directory under `specs/` to organize all specification documents. The directory should be named with a three-digit prefix followed by a kebab-case feature name (e.g., `specs/001-my-package-name/`). If other numbered directories already exist in `specs/`, use the next available number. -The design doc should (at least) include sections for: +## Design documents -- An overview +Develop **DETAILED** Markdown-formatted design documents that follow all of the guidance you have about Dart and Flutter design patterns, rules, best practices, and core principles. Feel free to use your available tools to research any aspects of the design that need clarification. + +Create the following files in the feature specification directory: + +### specs/NNN-feature-name/spec.md +The main specification document containing: +- An overview of the package - A detailed analysis of the goal or problem - Alternatives considered - A detailed design for the new package @@ -48,13 +54,33 @@ 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. +### specs/NNN-feature-name/data-model.md +A dedicated document for the data model containing: +- Entity definitions and relationships +- Data structures and types +- API contracts (if applicable) +- Data flow diagrams in Mermaid format + +### specs/NNN-feature-name/plan.md +A high-level plan document containing: +- Project milestones +- Key deliverables +- Dependencies and risks +- Success criteria + +### specs/NNN-feature-name/checklists/requirements.md +A requirements checklist containing: +- [ ] Functional requirements (checkboxed list) +- [ ] Non-functional requirements (checkboxed list) +- [ ] API requirements or acceptance criteria + +Be sure to **actually fetch and read** the research URLs **before** writing the design documents. 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. +You must ask the user to review these design documents and they must approve them before you continue on to create the implementation plan. They must review and approve 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 DESIGN.md document, Develop a **DETAILED** Markdown-formatted phased implementation plan of checkboxed tasks that need to be performed in order to finish developing the package. Save the implementation plan in specs/IMPLEMENTATION.md in the package directory. +After getting explicit approval from the user for the design documents, develop a **DETAILED** Markdown-formatted phased implementation plan of checkboxed tasks that need to be performed in order to finish developing the package. Save the implementation plan in `specs/NNN-feature-name/tasks.md` (in the same feature directory as the design documents). 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. @@ -81,8 +107,9 @@ The implementation plan should specify after each phase that you should: - [ ] 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 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. +- [ ] Re-read the tasks.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 tasks.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. +- [ ] Update the checklists/requirements.md file to check off any requirements that have been satisfied. - [ ] 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. @@ -92,9 +119,9 @@ In the last phase of the plan, include steps to: - [ ] 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. +You must ask the user to review the tasks.md 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 IMPLEMENTATION.md document, begin implementing the plan. +After getting explicit approval from the user for the tasks.md document, begin implementing the plan. """ diff --git a/commands/modify.toml b/commands/modify.toml index 0631860..ee58d64 100644 --- a/commands/modify.toml +++ b/commands/modify.toml @@ -31,13 +31,19 @@ First, make sure there are no uncommitted changes on the current branch. If ther If the user wants the work done on a new branch, create the branch now. -## Modification design document +## Feature specification directory -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. +Create a numbered feature directory under `specs/` to organize all specification documents. The directory should be named with a three-digit prefix followed by a kebab-case modification name (e.g., `specs/002-add-authentication/`). If other numbered directories already exist in `specs/`, use the next available number. -The design doc should (at least) include: +## Modification design documents -- An overview +Develop **DETAILED** Markdown-formatted design documents that follow all of the guidance you have about Dart and Flutter design patterns, rules, best practices, and core principles. Feel free to use your available tools to research any aspects of the modification that are unclear. + +Create the following files in the feature specification directory: + +### specs/NNN-feature-name/spec.md +The main specification document containing: +- An overview of the modification - A detailed analysis of the goal or problem - Alternatives considered - A detailed design for the modification @@ -46,13 +52,33 @@ The design doc should (at least) include: - 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. +### specs/NNN-feature-name/data-model.md +A dedicated document for data model changes (if applicable) containing: +- Entity modifications +- Schema changes +- State management updates +- Data flow diagrams in Mermaid format + +### specs/NNN-feature-name/plan.md +A high-level plan document containing: +- Modification milestones +- Key deliverables +- Dependencies and risks +- Success criteria + +### specs/NNN-feature-name/checklists/requirements.md +A requirements checklist containing: +- [ ] Functional requirements for this modification (checkboxed list) +- [ ] Non-functional requirements (checkboxed list) +- [ ] Acceptance criteria + +Be sure to **actually fetch and read** the research URLs **before** writing the design documents. 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. +You must ask the user to review these design documents and they must approve them before you continue on to create the implementation plan. They must review and approve 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. +After getting explicit approval from the user for the design documents, 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 `specs/NNN-feature-name/tasks.md` (in the same feature directory as the design documents). 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. @@ -68,8 +94,9 @@ The implementation plan should specify after each phase that you should: - [ ] 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. +- [ ] Re-read the tasks.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 tasks.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. +- [ ] Update the checklists/requirements.md file to check off any requirements that have been satisfied. - [ ] 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. @@ -81,9 +108,9 @@ In the last phase of the plan, include steps to: - [ ] 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. +You must ask the user to review the tasks.md 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. +After getting explicit approval from the user for the tasks.md document, begin implementing the plan. """ From fa422e0380d13ae7d4867ef90bd902ad07def35e Mon Sep 17 00:00:00 2001 From: Meylis Annagurbanov Date: Fri, 30 Jan 2026 23:21:46 +0500 Subject: [PATCH 5/5] fix: correct invalid Flutter version 3.37.0 to 3.35.0 Flutter version 3.37.0 does not exist - versions jump from 3.35.0 to 3.38.0. Hot reload became stable in Flutter 3.35.0, so this is the correct version to reference. Fixed in: create-app.toml, modify.toml, debug-app.toml, README.md --- README.md | 2 +- commands/create-app.toml | 2 +- commands/debug-app.toml | 4 ++-- commands/modify.toml | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e05be7f..35f99a0 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ page on dart.dev or the ## Known issues - Running a Flutter app from within Gemini CLI and then triggering a Hot Reload - does not work in Flutter stable <= 3.37.0. + does not work in Flutter stable <= 3.35.0. Tracking issue: [gemini-cli-extensions/flutter#15](https://github.com/gemini-cli-extensions/flutter/issues/15) ## 🐛 Troubleshooting diff --git a/commands/create-app.toml b/commands/create-app.toml index c60083c..52388e0 100644 --- a/commands/create-app.toml +++ b/commands/create-app.toml @@ -113,7 +113,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. - - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. + - Hot reload only works reliably on Flutter at versions at or above 3.35.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. In the last phase of the plan, include steps to: diff --git a/commands/debug-app.toml b/commands/debug-app.toml index d8873b3..097fc4a 100644 --- a/commands/debug-app.toml +++ b/commands/debug-app.toml @@ -34,7 +34,7 @@ Next, collect additional information required for debugging. Ask the user one qu Before diving into the code, let's verify the project's dependencies and environment. - [ ] Run `flutter doctor` to get the Flutter and Dart SDK versions and check for any issues reported. - - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. + - Hot reload only works reliably on Flutter at versions at or above 3.35.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. - [ ] Use the `pub` tool with the `outdated` command to look for outdated packages or dependency conflicts in `pubspec.yaml` and `pubspec.lock`. - Run the command `pub` tool with `upgrade` to upgrade to latest versions. - If that isn't sufficient, sometimes upgrading the package version to a new major version can help. The `pub` tool can't do this, so run the command `dart pub upgrade --major-versions` to do this. @@ -64,7 +64,7 @@ The debugging strategy should be chosen to yield the best results and may involv - **Logging and Tracing:** - Add strategic logging statements to the code to trace execution flow. Prefer `debugPrint()` over `print()` for cleaner, non-interfering output. - Use `hot_reload` to apply logging changes quickly while preserving the app's state. - - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. + - Hot reload only works reliably on Flutter at versions at or above 3.35.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. - If the state needs to be reset, explain that a Hot Restart is needed, and you will need to stop and restart the app. - **Flutter DevTools & UI Inspection:** diff --git a/commands/modify.toml b/commands/modify.toml index ee58d64..a8d747d 100644 --- a/commands/modify.toml +++ b/commands/modify.toml @@ -100,7 +100,7 @@ The implementation plan should specify after each phase that you should: - [ ] 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. - - Hot reload only works reliably on Flutter at versions at or above 3.37.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. + - Hot reload only works reliably on Flutter at versions at or above 3.35.0. If hot_reload fails, and they are using a version below that, inform the user and suggest either switching to the Flutter main channel or manually reloading the app. In the last phase of the plan, include steps to: