poc: Implement the specs + sample + AI

Author: nkhanh44

.github/workflows/android_deploy_production.yml

@@ -25,13 +25,12 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/android_deploy_production_to_playstore.yml

@@ -25,13 +25,12 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/android_deploy_staging.yml

@@ -25,13 +25,12 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/bump_version.yml

@@ -18,11 +18,8 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Set new version
-        uses: jossef/action-set-json-field@v2.1
-        with:
-          file: mason-config.json
-          field: app_version
-          value: ${{ github.event.inputs.newVersion }}
+        run: |
+          sed -i "s/^version: .*/version: ${{ github.event.inputs.newVersion }}/" sample/pubspec.yaml
 
       - name: Create pull request
         uses: peter-evans/create-pull-request@v4

.github/workflows/ios_deploy_staging_to_firebase.yml

@@ -35,13 +35,12 @@ jobs:
         uses: subosito/flutter-action@v1
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/ios_deploy_to_app_store.yml

@@ -36,13 +36,12 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/ios_deploy_to_testflight.yml

@@ -36,13 +36,12 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Set up project
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          cp -r sample/* .
+          cp -r sample/.* . 2>/dev/null || true
 
       - name: Get Flutter dependencies
         run: flutter pub get

.github/workflows/test.yml

@@ -1,13 +1,11 @@
 name: CI
 on:
-  # Trigger the workflow on push or pull request,
-  # but push action is only for the feature branch
   pull_request:
     types: [ opened, synchronize, reopened ]
 
 jobs:
-  test:
-    name: Template initializing scripts test
+  validate_sample:
+    name: Validate sample project
     runs-on: ubuntu-latest
     timeout-minutes: 30
     steps:
@@ -18,118 +16,36 @@ jobs:
         uses: subosito/flutter-action@v2
         with:
           channel: 'stable'
-          flutter-version: '3.10.5'
+          flutter-version: '3.24.3'
 
-      - name: Generate new project
+      - name: Check for spec drift
         run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json
+          SAMPLE_CHANGED=$(git diff --name-only origin/develop...HEAD -- sample/ | wc -l)
+          SPECS_CHANGED=$(git diff --name-only origin/develop...HEAD -- specs/ | wc -l)
+          if [ "$SAMPLE_CHANGED" -gt 0 ] && [ "$SPECS_CHANGED" -eq 0 ]; then
+            echo "::warning::sample/ changed but specs/ was not updated. Please review if specs need updating."
+          fi
 
-      - name: Get Flutter dependencies
-        run: flutter pub get
+      - name: Layer 1 — Structural validation
+        run: bash specs/validation/validate_structure.sh sample
 
-      - name: Run code generator
-        run: flutter packages pub run build_runner build --delete-conflicting-outputs
+      - name: Layer 2a — Get Flutter dependencies
+        run: cd sample && flutter pub get
 
-      - name: Check for any formatting issues in the code
-        run: dart format --set-exit-if-changed .
+      - name: Layer 2b — Run code generator
+        run: cd sample && flutter packages pub run build_runner build --delete-conflicting-outputs
 
-      - name: Statically analyze the Dart code for any errors
-        run: flutter analyze .
+      - name: Layer 2c — Check formatting
+        run: cd sample && dart format --set-exit-if-changed .
 
-      - name: Run widget tests, unit tests
-        run: flutter test --machine --coverage
+      - name: Layer 2d — Static analysis
+        run: cd sample && flutter analyze .
 
-  generate_mason_bundle:
-    # The job generate_mason_bundle identify that the job test must complete successfully
-    # before this generate_mason_bundle job will run
-    needs: test
-    name: Generate Mason bundle
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ github.head_ref }}
-
-      - name: Set up Flutter environment
-        uses: subosito/flutter-action@v2
-        with:
-          channel: 'stable'
-          flutter-version: '3.10.5'
-
-      - name: Install Mason CLI
-        run: |
-          dart pub global activate mason_cli
-          mason get
-
-      - name: Generate Mason bundle
-        run: |
-          mason bundle bricks/permission_handler -t dart -o bricks/template/hooks/bundles
-
-      - id: changes
-        name: Check for changes in the Mason bricks
-        run: |
-          count=$(git status bricks --porcelain | wc -l)
-          echo "count=$count" >> $GITHUB_OUTPUT
-
-      - name: Commit & push the Mason bundle changes
-        if: steps.changes.outputs.count > 0
-        run: |
-          git config user.name team-nimblehq
-          git config user.email bot@nimblehq.co
-          git add bricks
-          git commit -m "[Chore] Generate Mason bundle"
-          git push
-
-  generate_sample_project:
-    # The job generate_sample_project identify that the job generate_mason_bundle must complete successfully
-    # before this generate_sample_project job will run
-    needs: generate_mason_bundle
-    name: Generate the sample project
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Check out
-        uses: actions/checkout@v3
-        with:
-          ref: ${{ github.head_ref }}
-
-      - name: Set up Flutter environment
-        uses: subosito/flutter-action@v2
-        with:
-          channel: 'stable'
-          flutter-version: '3.10.5'
-
-      - name: Remove the old sample project
+      - name: Layer 3 — Architecture invariants
         run: |
-          rm -rf sample
+          cp specs/validation/invariant_architecture_test.dart sample/test/
+          cd sample && flutter test test/invariant_architecture_test.dart
+          rm -f test/invariant_architecture_test.dart
 
-      - name: Set the project name "sample"
-        uses: jossef/action-set-json-field@v2.1
-        with:
-          file: mason-config.json
-          field: project_name
-          value: sample
-
-      - name: Generate the new "sample" project
-        run: |
-          dart pub global activate mason_cli
-          mason get
-          mason make template -c mason-config.json -o sample
-
-      - id: changes
-        name: Check for changes in the sample project
-        run: |
-          count=$(git status sample --porcelain | wc -l)
-          echo "count=$count" >> $GITHUB_OUTPUT
-
-      - name: Commit & push the sample project changes
-        if: steps.changes.outputs.count > 0
-        run: |
-          git config user.name team-nimblehq
-          git config user.email bot@nimblehq.co
-          git add sample
-          git commit -m "[Chore] Generate & update sample project"
-          git push
+      - name: Layer 3b — Run tests
+        run: cd sample && flutter test --coverage

.gitignore

@@ -8,6 +8,16 @@
 *.iml
 .idea/*
 
-# Mason
-mason-lock.json
-.mason/
+# Generated projects (created by AI generation, not source of truth)
+*_project/
+*_app/
+
+# Build artifacts
+coverage/
+build/
+.dart_tool/
+
+# Flutter/Dart generated files (in case they leak to root)
+*.g.dart
+*.freezed.dart
+*.mocks.dart

AGENTS.md

@@ -0,0 +1,44 @@
+# AGENTS.md
+
+## Project
+
+Flutter project template using **spec-driven AI generation**. A golden reference project (`sample/`) + markdown specs + a validation pipeline replace traditional Mason/Mustache templates.
+
+## Repo structure
+
+```
+sample/          # Golden reference project (source of truth, CI-validated)
+specs/           # Generation prompt + architecture rules + validation scripts
+```
+
+## Generating a new project
+
+1. Fill in the 7 parameters in `specs/generation-prompt.md`
+2. Feed the prompt + `sample/` source code to an AI model
+3. AI generates the project into a fresh directory
+4. Run `bash specs/validation/validate.sh <project-path>`
+5. If validation fails, feed errors back to the AI and re-validate
+
+## Modifying the template
+
+1. Make the change in `sample/` first (real, runnable code)
+2. Run `bash specs/validation/validate.sh sample` — must pass
+3. If the change involves a non-obvious constraint, update `specs/architecture-rules.md`
+4. If the change affects generation parameters or checklist, update `specs/generation-prompt.md`
+5. Run validation again to confirm
+6. Never commit if validation fails
+
+## Validation
+
+```bash
+bash specs/validation/validate.sh sample
+```
+
+4 layers: structure, static analysis (`flutter analyze` + `dart format`), architecture invariants, unit tests.
+
+## Key rules
+
+- `sample/` is the sole source of truth for all code patterns — specs only document non-obvious constraints
+- Never generate `*.g.dart`, `*.freezed.dart`, `*.config.dart`, `*.mocks.dart`, or `lib/gen/` — these come from `build_runner` / `flutter_gen`
+- Domain layer must not import from data or app layers; data must not import from app
+- All Dart imports use `package:` format, never relative imports