agent-flutter 0.1.21 → 0.1.23

package/README.md

@@ -76,4 +76,4 @@ npm run release:major
 - Cursor: `.cursor/skills/`, `.cursor/rules/shared/`, `.cursor/scripts/`, `.cursor/rules/agent-flutter.mdc`
 - Windsurf: `.windsurf/skills/`, `.windsurf/rules/shared/`, `.windsurf/scripts/`, `.windsurf/rules/agent-flutter.md`
 - Cline: `.clinerules/skills/`, `.clinerules/rules/`, `.clinerules/scripts/`, `.clinerules/agent-flutter.md`
-- GitHub: `.github/skills/`, `.github/rules/`, `.github/scripts/`, `.github/copilot-instructions.md`
+- GitHub: `.github/skills/`, `.github/rules/`, `.github/scripts/`, `.github/copilot-instructions.md`, `.github/pull_request_template.md`, `.github/workflows/pr-template-gate.yml`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-flutter",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Portable Flutter skill/rule pack initializer for multiple AI IDEs.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -399,6 +399,25 @@ async function applyPack({
       });
       console.log(`${verb} GitHub rules: ${githubRulesPath}`);
     }
+
+    const githubPrTemplateSource = path.join(templateRoot, 'github', 'pull_request_template.md');
+    if (await exists(githubPrTemplateSource)) {
+      await syncTemplateFile({
+        sourcePath: githubPrTemplateSource,
+        destinationPath: path.join(projectRoot, '.github', 'pull_request_template.md'),
+        label: 'GitHub PR template',
+      });
+    }
+
+    const githubPrGateSource = path.join(templateRoot, 'github', 'workflows', 'pr-template-gate.yml');
+    if (await exists(githubPrGateSource)) {
+      await syncTemplateFile({
+        sourcePath: githubPrGateSource,
+        destinationPath: path.join(projectRoot, '.github', 'workflows', 'pr-template-gate.yml'),
+        label: 'GitHub PR gate workflow',
+      });
+    }
+
     const githubPath = path.join(projectRoot, '.github', 'copilot-instructions.md');
     const written = await writeTextFile(
       githubPath,
@@ -697,7 +716,7 @@ Use local instructions from \`.cursor\`.
 Priority:
 1. \`.cursor/rules/shared/ui.md\`
 2. \`.cursor/rules/shared/integration-api.md\`
-3. \`.cursor/rules/shared/document-workflow-function.md\`
+3. \`.cursor/rules/shared/ci-cd-pr.md\`
 4. \`.cursor/rules/shared/unit-test.md\` and \`.cursor/rules/shared/widget-test.md\`
 
 When a task matches a skill, load the corresponding \`SKILL.md\` under:
@@ -718,6 +737,7 @@ Required order:
 2. If task matches a skill, load \`.windsurf/skills/<skill>/SKILL.md\`.
 3. For new project scaffolding, run \`bash .windsurf/scripts/bootstrap_flutter_template.sh\`.
 4. Keep spec documentation synchronized after UI/API changes.
+5. For completed UI/API features, follow \`.windsurf/rules/shared/ci-cd-pr.md\` before handoff.
 `;
 }
 
@@ -732,6 +752,7 @@ Execution checklist:
 3. For new project scaffolding, run \`bash .clinerules/scripts/bootstrap_flutter_template.sh\`.
 4. Preserve Flutter architecture conventions and localization requirements.
 5. Update docs/specs after behavior changes.
+6. For completed UI/API features, follow \`.clinerules/rules/ci-cd-pr.md\` before handoff.
 `;
 }
 
@@ -746,6 +767,7 @@ Follow this order when generating code:
 3. For new project scaffolding, run \`bash .github/scripts/bootstrap_flutter_template.sh\`.
 4. Keep architecture, localization, and UI conventions aligned with local instructions.
 5. Update specs/docs when UI/API behavior changes.
+6. For completed UI/API features, follow \`.github/rules/ci-cd-pr.md\` before final handoff.
 `;
 }
 

package/templates/shared/TEMPLATES.md

@@ -52,3 +52,22 @@ Refactor this page: [Path to file]
 - Replace raw widgets with `App*` widgets.
 - Fix hardcoded strings/colors.
 ```
+
+---
+
+## **4. Finalize Feature (Commit + Push + PR)**
+
+Use this after completing UI/API work to trigger CI/CD rule and PR creation:
+
+```text
+Finalize this feature:
+- Branch name: [e.g. feat/login-session-timeout]
+- Commit message: [e.g. feat(auth): handle session timeout]
+- Base branch: [e.g. dev]
+- PR title: [e.g. feat(auth): handle session timeout]
+- Feature summary: [...]
+- UI summary: [...]
+- Reviewer notes: [...]
+- Screenshot evidence: [No UI OR before/after]
+- Paired with: [Solo OR name]
+```

package/templates/shared/github/pull_request_template.md

@@ -0,0 +1,26 @@
+### 🗃 Issue Or Explanation for this PR. (What is it supposed to do and Why is needed)
+
+- Feature:
+- UI:
+
+### ✅ Checklist
+
+- [ ] Issue Or Task detail are up to date for people to QA
+- [ ] I have functionally tested all my changes
+- [ ] I handled the code format
+- [ ] I have Tested on Android (only App)
+- [ ] I have Tested on iOS (only App)
+
+### 🕵️‍♂️ Notes for Code Reviewer
+
+Example: Change the Subscription Billing Flow with using SetupIntent to collect user billing information first.
+
+### 🙈 Screenshots
+
+No UI
+or take screenshot before change and after change
+Or take a screenshot of the design if the task is new
+
+### 👯‍♀️ Paired with
+
+Solo

package/templates/shared/github/workflows/pr-template-gate.yml

@@ -0,0 +1,102 @@
+name: PR Template Gate
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - reopened
+      - synchronize
+      - ready_for_review
+
+jobs:
+  validate-pr-template:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR body sections and checklist
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = (context.payload.pull_request.body || "").trim();
+            const errors = [];
+
+            function escapeRegExp(value) {
+              return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            }
+
+            function requirePattern(regex, message) {
+              if (!regex.test(body)) {
+                errors.push(message);
+              }
+            }
+
+            function sectionBetween(startHeading, endHeading) {
+              const start = body.indexOf(startHeading);
+              if (start === -1) return "";
+              const afterStart = start + startHeading.length;
+              const end = endHeading ? body.indexOf(endHeading, afterStart) : body.length;
+              const raw = end === -1 ? body.slice(afterStart) : body.slice(afterStart, end);
+              return raw.trim();
+            }
+
+            const requiredHeadings = [
+              "### 🗃 Issue Or Explanation for this PR. (What is it supposed to do and Why is needed)",
+              "### ✅ Checklist",
+              "### 🕵️‍♂️ Notes for Code Reviewer",
+              "### 🙈 Screenshots",
+              "### 👯‍♀️ Paired with",
+            ];
+
+            for (const heading of requiredHeadings) {
+              if (!body.includes(heading)) {
+                errors.push(`Missing section: ${heading}`);
+              }
+            }
+
+            requirePattern(/^- Feature:\s*\S.+/m, "Missing or empty `- Feature:` line.");
+            requirePattern(/^- UI:\s*\S.+/m, "Missing or empty `- UI:` line.");
+
+            const checklistItems = [
+              "Issue Or Task detail are up to date for people to QA",
+              "I have functionally tested all my changes",
+              "I handled the code format",
+              "I have Tested on Android (only App)",
+              "I have Tested on iOS (only App)",
+            ];
+
+            for (const item of checklistItems) {
+              const regex = new RegExp(`^- \\[(x|X)\\] ${escapeRegExp(item)}\\s*$`, "m");
+              if (!regex.test(body)) {
+                errors.push(`Checklist item must be checked [x]: ${item}`);
+              }
+            }
+
+            const notesSection = sectionBetween(
+              "### 🕵️‍♂️ Notes for Code Reviewer",
+              "### 🙈 Screenshots",
+            );
+            if (!notesSection || /^Example:/i.test(notesSection)) {
+              errors.push("Notes for Code Reviewer must contain actual reviewer notes, not only the example.");
+            }
+
+            const screenshotSection = sectionBetween(
+              "### 🙈 Screenshots",
+              "### 👯‍♀️ Paired with",
+            );
+            const hasNoUi = /No UI/i.test(screenshotSection);
+            const hasImage = /!\[[^\]]*\]\([^)]+\)/.test(screenshotSection);
+            const hasBeforeAfter = /before/i.test(screenshotSection) && /after/i.test(screenshotSection);
+            if (!screenshotSection || (!hasNoUi && !hasImage && !hasBeforeAfter)) {
+              errors.push("Screenshots section must include `No UI`, markdown image(s), or before/after evidence.");
+            }
+
+            const pairedSection = sectionBetween("### 👯‍♀️ Paired with", null);
+            if (!pairedSection) {
+              errors.push("Paired with section cannot be empty (e.g. `Solo`).");
+            }
+
+            if (errors.length > 0) {
+              core.setFailed(["PR template validation failed:", ...errors.map(e => `- ${e}`)].join("\n"));
+            } else {
+              core.info("PR template validation passed.");
+            }

package/templates/shared/rules/ci-cd-pr.md

@@ -0,0 +1,47 @@
+---
+alwaysApply: false
+---
+# CI/CD Rule - Commit, Push, Pull Request Gate
+
+## 1. Trigger
+Apply this rule after completing any feature that follows:
+- `ui.md`
+- `integration-api.md`
+
+This is the required "done" flow before feature handoff.
+
+## 2. Required Flow
+1. Verify quality gates:
+   - `fvm flutter analyze`
+   - Run related tests for the changed scope (unit/widget/integration when available).
+2. Ensure spec/docs are updated if behavior changed.
+3. Commit with clear scope and summary.
+4. Push branch to remote.
+5. Create PR with mandatory template sections.
+
+If any step is skipped, feature is not considered complete.
+
+## 3. Git Commands (Reference)
+```bash
+git checkout -b feat/<feature-name>
+git add -A
+git commit -m "feat(<scope>): <short summary>"
+git push -u origin HEAD
+```
+
+## 4. PR Body Policy (Mandatory)
+PR must follow `.github/pull_request_template.md` and include all sections:
+- Issue/Explanation (with `Feature` and `UI` lines).
+- Checklist (all required items checked `[x]`).
+- Notes for reviewer.
+- Screenshots section (`No UI` or actual screenshots/evidence).
+- Paired with.
+
+## 5. Merge Gate
+- CI workflow `PR Template Gate` validates PR body.
+- If required section/checklist is missing, CI fails.
+- Branch protection must require this check before merge.
+
+## 6. Agent Behavior
+- After finishing UI/API tasks, agent must complete commit + push + PR creation.
+- Agent should return PR URL as final output for the task.

package/templates/shared/rules/document-workflow-function.md

@@ -1,98 +0,0 @@
----
-alwaysApply: false
----
-# AI Documentation Workflow (Function)
-
-## **Goal**
-To automatically generate and maintain detailed functional documentation in `spec/function-workflow.md`. This documentation bridges the gap between the high-level UI flow (from `ui-workflow.md`) and the technical implementation, focusing on **API integrations, Data Transformations, and State Management logic**.
-
-## **Trigger**
-This workflow is triggered when:
-1.  The `spec/ui-workflow.md` has been updated (Prerequisite).
-2.  Backend integration (API) is implemented for a feature.
-3.  Complex business logic is added (e.g., data validation, caching, error handling).
-4.  The user requests: "Update function workflow for [feature]".
-
-## **Workflow Steps**
-
-### **Step 1: Analyze the Implementation**
-- **Input**: The feature folder (`lib/src/ui/<feature>`) and `spec/ui-workflow.md`.
-- **Action**: Deep dive into the following files:
-    - `bloc/*_bloc.dart`: Identify Events, States, and Side Effects.
-    - `repository/*_repository.dart`: Identify API endpoints, Request/Response models.
-    - `model/*`: Analyze data structures.
-    - `core/managers/*`: Check for global state usage (e.g., Auth, Permission).
-
-### **Step 2: Format the Documentation**
-- **Output File**: `spec/function-workflow.md`
-- **Format**: Append (or Update) a section for EACH feature using the following template:
-
-```markdown
-## [Feature Name] (e.g., Login)
-**Ref UI**: [Link to UI Spec Section]
-
-### **1. Data Model**
-**Request**: `LoginRequest`
-- `email` (String): Required, valid email format.
-- `password` (String): Required, min 6 chars.
-
-**Response**: `LoginResponse`
-- `token` (String): JWT Token.
-- `user` (UserDto): User profile info.
-
-### **2. State Management (BLoC)**
-**Events**:
-- `LoginEvent(email, password)`: Triggers the login process.
-- `LoginReset()`: Resets state to initial.
-
-**States**:
-- `LoginInitial`: Form inputs enabled.
-- `LoginLoading`: Inputs disabled, loading spinner active.
-- `LoginSuccess(user)`: Navigation trigger.
-- `LoginFailure(error)`: Error message display.
-
-### **3. Functional Logic**
-1.  **Validation**:
-    - Check `email` via Regex.
-    - Check `password.length >= 6`.
-    - *If invalid*: Emit `LoginFailure(ValidationError)`.
-
-2.  **API Call**:
-    - Call `AuthRepository.login(request)`.
-    - **Endpoint**: `POST /api/v1/auth/login`
-    - **Headers**: `Content-Type: application/json`
-
-3.  **Error Handling**:
-    - **401 Unauthorized**: "Incorrect credentials".
-    - **500 Server Error**: "System error, try again".
-    - **Network Error**: "Check connection".
-
-4.  **Post-Process**:
-    - Save `token` to `SecureStorage`.
-    - Update `UserManager.currentUser`.
-    - Emit `LoginSuccess`.
-
-### **4. Dependencies & Services**
-- `AuthRepository`: API communication.
-- `SecureStorage`: Token persistence.
-- `UserManager`: Global user state.
-
-### **5. Technical Debt / Optimization**
-- [ ] Add rate limiting on login attempts.
-- [ ] Cache last used email for convenience.
-```
-
-### **Step 3: Verification**
-- **Consistency Check**: Ensure the "Functional Logic" aligns with the "User Flow" in `spec/ui-workflow.md`.
-- **API Check**: Verify that the documented Endpoint and Request/Response models match the actual code in `Repository` and `Retrofit` clients.
-- **Edge Cases**: Ensure error handling (Network, Validation, Server) is documented.
-
----
-
-## **Prompt for AI**
-
-### **Case 1: Single Feature**
-> "Analyze `lib/src/ui/<feature>` and update `spec/function-workflow.md` based on the UI spec."
-
-### **Case 2: Sync with UI Spec**
-> "Read `spec/ui-workflow.md` and generate the corresponding functional specs in `spec/function-workflow.md`."

package/templates/shared/rules/new-template-project.md

@@ -1,51 +0,0 @@
----
-alwaysApply: false
----
-# New Template Project (Script-first)
-
-Use the bootstrap script instead of generating the full workflow text.
-
-## Script path
-- Trae: `.trae/scripts/bootstrap_flutter_template.sh`
-- Codex: `.codex/scripts/bootstrap_flutter_template.sh`
-- Cursor: `.cursor/scripts/bootstrap_flutter_template.sh`
-- Windsurf: `.windsurf/scripts/bootstrap_flutter_template.sh`
-- Cline: `.clinerules/scripts/bootstrap_flutter_template.sh`
-- GitHub: `.github/scripts/bootstrap_flutter_template.sh`
-
-## Run
-Interactive mode:
-```bash
-bash .codex/scripts/bootstrap_flutter_template.sh
-```
-
-Non-interactive mode:
-```bash
-bash .codex/scripts/bootstrap_flutter_template.sh \
-  --name link_home_mobile \
-  --org com.company \
-  --flutter-version stable \
-  --dir ~/workspace \
-  --force \
-  --non-interactive
-```
-
-## Inputs
-- `--name`: project folder name (required in non-interactive mode).
-- `--org`: reverse-domain org id (default: `com.example`).
-- `--flutter-version`: Flutter version for FVM (default: `stable`).
-- `--dir`: parent folder to create project in (default: current directory).
-- `--force`: allow overwrite in an existing non-empty directory.
-
-## What the script does
-1. Ensures FVM exists (auto-installs with `dart pub global activate fvm` if needed).
-2. Creates Flutter project with FVM and selected version.
-3. Adds core dependencies and dev dependencies.
-4. Creates architecture folders and starter files (`main`, DI, locale, routing, home feature).
-5. Creates `.env`, `.env.staging`, `.env.prod` and updates `.gitignore`.
-
-## Validation
-```bash
-cd <project_name>
-fvm flutter run
-```