agent-flutter 0.1.22 → 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.22",
+  "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,8 @@ Use local instructions from \`.cursor\`.
 Priority:
 1. \`.cursor/rules/shared/ui.md\`
 2. \`.cursor/rules/shared/integration-api.md\`
-3. \`.cursor/rules/shared/unit-test.md\` and \`.cursor/rules/shared/widget-test.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:
 \`.cursor/skills/<skill>/SKILL.md\`
@@ -717,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.
 `;
 }
 
@@ -731,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.
 `;
 }
 
@@ -745,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.