agent-flutter 0.1.2 → 0.1.4

package/README.md

@@ -26,6 +26,24 @@ npx agent-flutter@latest sync --ide trae,codex,github
 npx agent-flutter@latest list --cwd /path/to/project
 ```
 
+## Bootstrap new Flutter project (script)
+
+After `init`, run the script from the IDE-specific folder:
+
+```bash
+bash .trae/scripts/bootstrap_flutter_template.sh
+```
+
+Examples by IDE:
+
+```bash
+bash .codex/scripts/bootstrap_flutter_template.sh
+bash .cursor/scripts/bootstrap_flutter_template.sh
+bash .windsurf/scripts/bootstrap_flutter_template.sh
+bash .clinerules/scripts/bootstrap_flutter_template.sh
+bash .github/scripts/bootstrap_flutter_template.sh
+```
+
 ## Publish to npm (one-time setup, Trusted Publishing)
 
 1. On npm package settings, add a **Trusted publisher**:
@@ -52,10 +70,9 @@ npm run release:major
 
 ## Installed files
 
-- Shared pack: `.agent-flutter/`
-- Trae: `.trae/`
-- Codex: `AGENTS.md`
-- Cursor: `.cursor/rules/agent-flutter.mdc`
-- Windsurf: `.windsurf/rules/agent-flutter.md`
-- Cline: `.clinerules/agent-flutter.md`
-- GitHub: `.github/copilot-instructions.md`
+- Trae: `.trae/` (skills/rules/scripts)
+- Codex: `.codex/` + `AGENTS.md`
+- 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`

package/package.json

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

package/src/cli.js

@@ -13,9 +13,9 @@ Usage:
   npx agent-flutter@latest list [--cwd <project_dir>]
 
 Commands:
-  init   Install shared Flutter skills/rules and IDE adapters.
-  sync   Update installed shared pack and adapters from latest template.
-  list   Print available skills/rules from the shared pack.
+  init   Install Flutter skills/rules/scripts for selected IDE adapters.
+  sync   Update installed adapters from latest template.
+  list   Print available skills/rules from package template.
 `;
 
 export async function runCli(argv) {
@@ -142,38 +142,50 @@ async function applyPack({
   mode,
 }) {
   const verb = mode === 'sync' ? 'Synced' : 'Installed';
-  const sharedTarget = path.join(projectRoot, '.agent-flutter');
-  if ((await exists(sharedTarget)) && !force) {
-    console.log(`Using existing shared pack: ${sharedTarget}`);
-  } else {
+  const syncDirectory = async ({ sourceDir, destinationDir, label }) => {
+    if ((await exists(destinationDir)) && !force) {
+      console.log(`Skipped ${label} (exists): ${destinationDir}`);
+      return;
+    }
     await copyTemplateDirectory({
-      sourceDir: templateRoot,
-      destinationDir: sharedTarget,
+      sourceDir,
+      destinationDir,
       projectRoot,
       force: true,
     });
-    console.log(`${verb} shared pack: ${sharedTarget}`);
-  }
+    console.log(`${verb} ${label}: ${destinationDir}`);
+  };
 
   if (ideTargets.has('trae')) {
     const traeTarget = path.join(projectRoot, '.trae');
-    if ((await exists(traeTarget)) && !force) {
-      console.log(`Skipped Trae adapter (exists): ${traeTarget}`);
-    } else {
-      await copyTemplateDirectory({
-        sourceDir: templateRoot,
-        destinationDir: traeTarget,
-        projectRoot,
-        force: true,
-      });
-      console.log(`${verb} Trae adapter: ${traeTarget}`);
-    }
+    await syncDirectory({
+      sourceDir: templateRoot,
+      destinationDir: traeTarget,
+      label: 'Trae adapter',
+    });
   }
 
-  const skills = await loadSkillMetadata(path.join(sharedTarget, 'skills'));
-  const rules = await loadRuleMetadata(path.join(sharedTarget, 'rules'));
+  const skills = await loadSkillMetadata(path.join(templateRoot, 'skills'));
+  const rules = await loadRuleMetadata(path.join(templateRoot, 'rules'));
 
   if (ideTargets.has('codex')) {
+    const codexRoot = path.join(projectRoot, '.codex');
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'skills'),
+      destinationDir: path.join(codexRoot, 'skills'),
+      label: 'Codex skills',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'scripts'),
+      destinationDir: path.join(codexRoot, 'scripts'),
+      label: 'Codex scripts',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'rules'),
+      destinationDir: path.join(codexRoot, 'rules'),
+      label: 'Codex rules',
+    });
+
     const agentsPath = path.join(projectRoot, 'AGENTS.md');
     const written = await writeTextFile(
       agentsPath,
@@ -182,6 +194,7 @@ async function applyPack({
         projectName: path.basename(projectRoot),
         skills,
         rules,
+        packRoot: '.codex',
       }),
       { force },
     );
@@ -193,6 +206,22 @@ async function applyPack({
   }
 
   if (ideTargets.has('cursor')) {
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'skills'),
+      destinationDir: path.join(projectRoot, '.cursor', 'skills'),
+      label: 'Cursor skills',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'scripts'),
+      destinationDir: path.join(projectRoot, '.cursor', 'scripts'),
+      label: 'Cursor scripts',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'rules'),
+      destinationDir: path.join(projectRoot, '.cursor', 'rules', 'shared'),
+      label: 'Cursor rules',
+    });
+
     const cursorPath = path.join(projectRoot, '.cursor', 'rules', 'agent-flutter.mdc');
     const written = await writeTextFile(
       cursorPath,
@@ -207,6 +236,22 @@ async function applyPack({
   }
 
   if (ideTargets.has('windsurf')) {
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'skills'),
+      destinationDir: path.join(projectRoot, '.windsurf', 'skills'),
+      label: 'Windsurf skills',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'scripts'),
+      destinationDir: path.join(projectRoot, '.windsurf', 'scripts'),
+      label: 'Windsurf scripts',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'rules'),
+      destinationDir: path.join(projectRoot, '.windsurf', 'rules', 'shared'),
+      label: 'Windsurf rules',
+    });
+
     const windsurfPath = path.join(projectRoot, '.windsurf', 'rules', 'agent-flutter.md');
     const written = await writeTextFile(
       windsurfPath,
@@ -221,6 +266,22 @@ async function applyPack({
   }
 
   if (ideTargets.has('cline')) {
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'skills'),
+      destinationDir: path.join(projectRoot, '.clinerules', 'skills'),
+      label: 'Cline skills',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'scripts'),
+      destinationDir: path.join(projectRoot, '.clinerules', 'scripts'),
+      label: 'Cline scripts',
+    });
+    await syncDirectory({
+      sourceDir: path.join(templateRoot, 'rules'),
+      destinationDir: path.join(projectRoot, '.clinerules', 'rules'),
+      label: 'Cline rules',
+    });
+
     const clinePath = path.join(projectRoot, '.clinerules', 'agent-flutter.md');
     const written = await writeTextFile(
       clinePath,
@@ -235,6 +296,45 @@ async function applyPack({
   }
 
   if (ideTargets.has('github')) {
+    const githubSkillsPath = path.join(projectRoot, '.github', 'skills');
+    if ((await exists(githubSkillsPath)) && !force) {
+      console.log(`Skipped GitHub skills (exists): ${githubSkillsPath}`);
+    } else {
+      await copyTemplateDirectory({
+        sourceDir: path.join(templateRoot, 'skills'),
+        destinationDir: githubSkillsPath,
+        projectRoot,
+        force: true,
+      });
+      console.log(`${verb} GitHub skills: ${githubSkillsPath}`);
+    }
+
+    const githubScriptsPath = path.join(projectRoot, '.github', 'scripts');
+    if ((await exists(githubScriptsPath)) && !force) {
+      console.log(`Skipped GitHub scripts (exists): ${githubScriptsPath}`);
+    } else {
+      await copyTemplateDirectory({
+        sourceDir: path.join(templateRoot, 'scripts'),
+        destinationDir: githubScriptsPath,
+        projectRoot,
+        force: true,
+      });
+      console.log(`${verb} GitHub scripts: ${githubScriptsPath}`);
+    }
+
+    const githubRulesPath = path.join(projectRoot, '.github', 'rules');
+    if ((await exists(githubRulesPath)) && !force) {
+      console.log(`Skipped GitHub rules (exists): ${githubRulesPath}`);
+    } else {
+      await copyTemplateDirectory({
+        sourceDir: path.join(templateRoot, 'rules'),
+        destinationDir: githubRulesPath,
+        projectRoot,
+        force: true,
+      });
+      console.log(`${verb} GitHub rules: ${githubRulesPath}`);
+    }
+
     const githubPath = path.join(projectRoot, '.github', 'copilot-instructions.md');
     const written = await writeTextFile(
       githubPath,
@@ -250,32 +350,34 @@ async function applyPack({
 }
 
 async function detectInstalledIdeTargets(projectRoot) {
-  const checks = [
-    ['trae', path.join(projectRoot, '.trae')],
-    ['codex', path.join(projectRoot, 'AGENTS.md')],
-    ['cursor', path.join(projectRoot, '.cursor', 'rules', 'agent-flutter.mdc')],
-    ['windsurf', path.join(projectRoot, '.windsurf', 'rules', 'agent-flutter.md')],
-    ['cline', path.join(projectRoot, '.clinerules', 'agent-flutter.md')],
-    ['github', path.join(projectRoot, '.github', 'copilot-instructions.md')],
-  ];
-
-  const results = await Promise.all(
-    checks.map(async ([ide, targetPath]) => [ide, await exists(targetPath)]),
-  );
-
   const detected = new Set();
-  for (const [ide, installed] of results) {
-    if (installed) detected.add(ide);
+  if (await exists(path.join(projectRoot, '.trae'))) detected.add('trae');
+  if (
+    (await exists(path.join(projectRoot, 'AGENTS.md')))
+    || (await exists(path.join(projectRoot, '.codex', 'skills')))
+  ) {
+    detected.add('codex');
+  }
+  if (await exists(path.join(projectRoot, '.cursor', 'rules', 'agent-flutter.mdc'))) {
+    detected.add('cursor');
+  }
+  if (await exists(path.join(projectRoot, '.windsurf', 'rules', 'agent-flutter.md'))) {
+    detected.add('windsurf');
+  }
+  if (await exists(path.join(projectRoot, '.clinerules', 'agent-flutter.md'))) {
+    detected.add('cline');
+  }
+  if (
+    (await exists(path.join(projectRoot, '.github', 'copilot-instructions.md')))
+    || (await exists(path.join(projectRoot, '.github', 'skills')))
+  ) {
+    detected.add('github');
   }
   return detected;
 }
 
 async function runList(options) {
-  const projectRoot = path.resolve(options.get('cwd', process.cwd()));
-  const sharedTarget = path.join(projectRoot, '.agent-flutter');
-  const templateRoot = await exists(sharedTarget)
-    ? sharedTarget
-    : path.join(getPackageRoot(), 'templates', 'shared');
+  const templateRoot = path.join(getPackageRoot(), 'templates', 'shared');
 
   const skills = await loadSkillMetadata(path.join(templateRoot, 'skills'));
   const rules = await loadRuleMetadata(path.join(templateRoot, 'rules'));
@@ -373,6 +475,7 @@ async function copyTemplateEntries({ sourceDir, destinationDir, projectRoot }) {
     } else {
       await fs.copyFile(fromPath, toPath);
     }
+    await copyFileMode(fromPath, toPath);
   }
 }
 
@@ -484,23 +587,29 @@ function parseFrontmatter(content) {
   return data;
 }
 
-function buildCodexAgents({ projectRoot, projectName, skills, rules }) {
+function buildCodexAgents({
+  projectRoot,
+  projectName,
+  skills,
+  rules,
+  packRoot,
+}) {
   const lines = [];
   lines.push(`# AGENTS.md instructions for ${projectName}`);
   lines.push('');
-  lines.push('## Agent Flutter Shared Pack');
-  lines.push('This project uses a shared local pack installed at `.agent-flutter`.');
+  lines.push('## Agent Flutter Local Pack');
+  lines.push(`This project uses local instructions installed at \`${packRoot}\`.`);
   lines.push('');
   lines.push('### Available skills');
   for (const skill of skills) {
     lines.push(
-      `- ${skill.slug}: ${skill.description || 'No description'} (file: ${toPosixPath(skill.path)})`,
+      `- ${skill.slug}: ${skill.description || 'No description'} (file: ${path.posix.join(packRoot, 'skills', skill.slug, 'SKILL.md')})`,
     );
   }
   lines.push('');
   lines.push('### Available rules');
   for (const rule of rules) {
-    lines.push(`- ${rule.file} (file: ${toPosixPath(rule.path)})`);
+    lines.push(`- ${rule.file} (file: ${path.posix.join(packRoot, 'rules', rule.file)})`);
   }
   lines.push('');
   lines.push('### Trigger rules');
@@ -510,64 +619,69 @@ function buildCodexAgents({ projectRoot, projectName, skills, rules }) {
   lines.push('');
   lines.push('### Location policy');
   lines.push(`- Project root: ${toPosixPath(projectRoot)}`);
-  lines.push('- Shared pack root: `.agent-flutter`');
-  lines.push('- Do not duplicate skill/rule content outside the shared pack unless required.');
+  lines.push(`- Local pack root: \`${packRoot}\``);
   return `${lines.join('\n')}\n`;
 }
 
 function buildCursorRule() {
   return `---
-description: Agent Flutter shared skills and rules
+description: Agent Flutter local skills and rules
 alwaysApply: false
 ---
-Use shared instructions from \`.agent-flutter\`.
+Use local instructions from \`.cursor\`.
 
 Priority:
-1. \`.agent-flutter/rules/ui.md\`
-2. \`.agent-flutter/rules/integration-api.md\`
-3. \`.agent-flutter/rules/document-workflow-function.md\`
-4. \`.agent-flutter/rules/unit-test.md\` and \`.agent-flutter/rules/widget-test.md\`
+1. \`.cursor/rules/shared/ui.md\`
+2. \`.cursor/rules/shared/integration-api.md\`
+3. \`.cursor/rules/shared/document-workflow-function.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:
-\`.agent-flutter/skills/<skill>/SKILL.md\`
+\`.cursor/skills/<skill>/SKILL.md\`
+
+For new project scaffolding, run:
+\`bash .cursor/scripts/bootstrap_flutter_template.sh\`
 `;
 }
 
 function buildWindsurfRule() {
   return `# Agent Flutter Rules
 
-Use the shared rule/skill pack at \`.agent-flutter\`.
+Use local instructions in \`.windsurf\`.
 
 Required order:
-1. Apply relevant files in \`.agent-flutter/rules/\`.
-2. If task matches a skill, load \`.agent-flutter/skills/<skill>/SKILL.md\`.
-3. Keep spec documentation synchronized after UI/API changes.
+1. Apply relevant files in \`.windsurf/rules/shared/\`.
+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.
 `;
 }
 
 function buildClineRule() {
   return `# Agent Flutter Cline Rule
 
-This repository uses shared instructions in \`.agent-flutter\`.
+This repository uses local instructions in \`.clinerules\`.
 
 Execution checklist:
-1. Read matching rule files under \`.agent-flutter/rules\`.
-2. Apply matching skills from \`.agent-flutter/skills\`.
-3. Preserve Flutter architecture conventions and localization requirements.
-4. Update docs/specs after behavior changes.
+1. Read matching rule files under \`.clinerules/rules\`.
+2. Apply matching skills from \`.clinerules/skills\`.
+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.
 `;
 }
 
 function buildGithubCopilotInstructions() {
   return `# Agent Flutter Copilot Instructions
 
-This repository uses a shared local instruction pack in \`.agent-flutter\`.
+This repository uses local instruction packs in \`.github/skills\`, \`.github/rules\`, and \`.github/scripts\`.
 
 Follow this order when generating code:
-1. Read applicable files in \`.agent-flutter/rules/\`.
-2. If task matches a skill, read \`.agent-flutter/skills/<skill>/SKILL.md\`.
-3. Keep architecture, localization, and UI conventions aligned with the shared pack.
-4. Update specs/docs when UI/API behavior changes.
+1. Read applicable files in \`.github/rules/\`.
+2. If task matches a skill, read \`.github/skills/<skill>/SKILL.md\`.
+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.
 `;
 }
 
@@ -588,6 +702,15 @@ async function safeStat(filePath) {
   }
 }
 
+async function copyFileMode(fromPath, toPath) {
+  try {
+    const fromStat = await fs.stat(fromPath);
+    await fs.chmod(toPath, fromStat.mode);
+  } catch {
+    // ignore permission propagation failures on unsupported filesystems
+  }
+}
+
 function toPosixPath(value) {
   return String(value || '').replaceAll('\\', '/');
 }

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

@@ -1,148 +1,51 @@
 ---
 alwaysApply: false
 ---
-# Template Project Creation Workflow
-
-This workflow describes the step-by-step process to generate a new Flutter project that matches the architecture and standards of the current codebase.
-
-## 1. Project Initialization (FVM)
-
-### 1.1 FVM Setup & Create Project
-Use FVM (Flutter Version Management) to ensure consistent Flutter versions.
-
-1.  **Install FVM** (if needed):
-    ```bash
-    dart pub global activate fvm
-    ```
-
-2.  **Initialize & Create Project**:
-    ```bash
-    mkdir project_name
-    cd project_name
-    
-    # Initialize FVM with specific version (e.g., 3.38.5)
-    fvm use 3.38.5 --force
-    
-    # Create project using FVM version
-    fvm flutter create . --org com.example
-    ```
-
-### 1.2 IDE Configuration (VS Code)
-Create/Update `.vscode/settings.json` to use the FVM version:
-```json
-{
-  "dart.flutterSdkPath": ".fvm/flutter_sdk",
-  "search.exclude": {
-    "**/.fvm": true
-  },
-  "files.watcherExclude": {
-    "**/.fvm": true
-  }
-}
+# 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
 ```
 
-### 1.3 Update `pubspec.yaml`
-Add the standard dependencies required for the project architecture.
-
-**Core Dependencies:**
-- `get`: ^4.6.x (Routing & DI)
-- `flutter_bloc`: ^8.x.x (State Management)
-- `equatable`: ^2.x.x
-- `dio`: ^5.x.x (Network)
-- `retrofit`: ^4.x.x (API Client)
-- `json_annotation`: ^4.x.x
-- `flutter_dotenv`: (Environment variables)
-- `flutter_svg`: (SVG support)
-- `intl`: (Formatting)
-
-**Dev Dependencies:**
-- `build_runner`: (Code generation)
-- `retrofit_generator`:
-- `json_serializable`:
-
-## 2. Directory Structure Scaffolding
-
-Remove the default `lib/main.dart` and create the following directory structure under `lib/src/`:
-
-```
-lib/
-  main.dart
-  src/
-    api/              # Retrofit API clients & interceptors
-    core/
-      managers/       # System managers (Permission, Connectivity)
-      model/          # Data models (Request/Response)
-      repository/     # Data repositories
-    di/               # Dependency Injection setup
-    enums/            # App-wide enums
-    extensions/       # Dart extensions (Theme, Color, String)
-    helper/           # Utils helpers (Validation, Logger)
-    locale/           # Localization (TranslationManager)
-    ui/               # Feature modules
-      base/           # Base classes (BasePage, BaseViewModel)
-      main/           # Root/Shell Page (BottomNav)
-      home/           # Home Feature
-      widgets/        # Shared UI components (AppInput, AppButton)
-      routing/        # Per-tab Routers
-    utils/            # Constants, Colors, Styles, Assets
+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
 ```
 
-## 3. Core Module Setup
-
-### 3.1 Dependency Injection (`lib/src/di/`)
-Create `di_graph_setup.dart` to initialize core services before the app starts.
-- **Components**:
-    - `EnvironmentModule`: Load `.env` config.
-    - `NetworkModule`: Setup Dio client.
-    - `RepositoryModule`: Register Repositories.
-    - `ManagerModule`: Register Global Managers.
-
-### 3.2 Utilities (`lib/src/utils/`)
-Create placeholder files for design system constants:
-- `app_colors.dart`: Define `AppColors` class.
-- `app_styles.dart`: Define `AppStyles` class.
-- `app_assets.dart`: Define `AppAssets` class.
-- `app_pages.dart`: Define `AppPages` (GetX Route definition).
-
-### 3.3 Localization (`lib/src/locale/`)
-Implement `TranslationManager` extending `Translations` from GetX.
-
-## 4. App Entry Point (`main.dart`)
-
-Configure `main.dart` to:
-1. Load Environment variables (`dotenv`).
-2. Initialize Dependencies (`setupDependenciesGraph()`).
-3. Run `GetMaterialApp` with:
-   - `initialRoute`: `AppPages.main`
-   - `getPages`: `AppPages.pages`
-   - `theme`: Custom Theme.
-
-## 5. Main Shell Implementation (Bottom Navigation)
-
-Follow the guide in `create-bottombar.md` to implement the root navigation shell.
-
-1.  **Enums**: Create `BottomNavigationPage` enum in `lib/src/enums/`.
-2.  **Bloc**: Create `MainBloc` in `lib/src/ui/main/bloc/` to manage tab state.
-3.  **UI**: Create `MainPage` using `IndexedStack` and `CupertinoTabView` for nested navigation.
-4.  **Widget**: Create `AppBottomNavigationBar`.
-
-## 6. Base Feature Creation (Home)
-
-Create a standard "Home" feature to verify the setup:
-1.  **Folder**: `lib/src/ui/home/`.
-2.  **Files**:
-    - `home_page.dart`: The UI.
-    - `bloc/home_bloc.dart`: The Logic.
-    - `binding/home_binding.dart`: DI for the module.
-3.  **Routing**:
-    - Add `HomeRouter` in `lib/src/ui/routing/`.
-    - Register in `AppPages`.
-
-## 7. Environment Setup
-
-Create root-level environment files:
-- `.env`
-- `.env.staging`
-- `.env.prod`
-
-Add `.env*` to `.gitignore`.
+## 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
+```

package/templates/shared/scripts/bootstrap_flutter_template.sh

@@ -0,0 +1,508 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Bootstrap a new Flutter template project (script-first workflow).
+
+Usage:
+  bootstrap_flutter_template.sh [options]
+
+Options:
+  -n, --name <project_name>        Project folder name (required if --non-interactive)
+  -o, --org <org_id>               Reverse-domain org id (default: com.example)
+  -f, --flutter-version <version>  Flutter version for FVM (default: stable)
+  -d, --dir <parent_dir>           Parent directory (default: current dir)
+      --force                      Allow create/overwrite in non-empty existing directory
+      --non-interactive            Do not prompt for missing values
+  -h, --help                       Show this help
+
+Examples:
+  ./bootstrap_flutter_template.sh
+  ./bootstrap_flutter_template.sh --name my_app --org com.company --flutter-version 3.38.5
+  ./bootstrap_flutter_template.sh --name crm_mobile --dir ~/workspace --force
+EOF
+}
+
+PROJECT_NAME=""
+ORG_ID="com.example"
+FLUTTER_VERSION="stable"
+PARENT_DIR="$(pwd)"
+FORCE=0
+NON_INTERACTIVE=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -n|--name)
+      PROJECT_NAME="${2:-}"
+      shift 2
+      ;;
+    -o|--org)
+      ORG_ID="${2:-}"
+      shift 2
+      ;;
+    -f|--flutter-version)
+      FLUTTER_VERSION="${2:-}"
+      shift 2
+      ;;
+    -d|--dir)
+      PARENT_DIR="${2:-}"
+      shift 2
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --non-interactive)
+      NON_INTERACTIVE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+prompt_required() {
+  local current="$1"
+  local message="$2"
+  if [[ -n "$current" ]]; then
+    printf '%s' "$current"
+    return
+  fi
+  if [[ "$NON_INTERACTIVE" -eq 1 ]]; then
+    printf '%s' ""
+    return
+  fi
+  read -r -p "$message" current
+  printf '%s' "$current"
+}
+
+prompt_with_default() {
+  local current="$1"
+  local message="$2"
+  local fallback="$3"
+  local input=""
+
+  if [[ "$NON_INTERACTIVE" -eq 1 ]]; then
+    if [[ -n "$current" ]]; then
+      printf '%s' "$current"
+    else
+      printf '%s' "$fallback"
+    fi
+    return
+  fi
+
+  read -r -p "$message" input
+  if [[ -n "$input" ]]; then
+    printf '%s' "$input"
+    return
+  fi
+
+  if [[ -n "$current" ]]; then
+    printf '%s' "$current"
+  else
+    printf '%s' "$fallback"
+  fi
+}
+
+normalize_project_name() {
+  local value="$1"
+  value="$(printf '%s' "$value" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9_]+/_/g; s/_+/_/g; s/^_+|_+$//g')"
+  if [[ -z "$value" ]]; then
+    value="flutter_app"
+  fi
+  if [[ "$value" =~ ^[0-9] ]]; then
+    value="app_$value"
+  fi
+  printf '%s' "$value"
+}
+
+ensure_fvm() {
+  if [[ -d "$HOME/.pub-cache/bin" ]]; then
+    export PATH="$HOME/.pub-cache/bin:$PATH"
+  fi
+  if command -v fvm >/dev/null 2>&1; then
+    return
+  fi
+  if ! command -v dart >/dev/null 2>&1; then
+    echo "Error: fvm not found and dart not available to install fvm." >&2
+    exit 1
+  fi
+  echo "Installing FVM..."
+  dart pub global activate fvm >/dev/null
+  export PATH="$PATH:$HOME/.pub-cache/bin"
+  if ! command -v fvm >/dev/null 2>&1; then
+    echo "Error: fvm installation failed." >&2
+    exit 1
+  fi
+}
+
+ensure_line_in_file() {
+  local file="$1"
+  local line="$2"
+  touch "$file"
+  if ! grep -Fxq "$line" "$file"; then
+    printf '%s\n' "$line" >>"$file"
+  fi
+}
+
+PROJECT_NAME="$(prompt_required "$PROJECT_NAME" "Project name: ")"
+if [[ -z "$PROJECT_NAME" ]]; then
+  echo "Error: project name is required." >&2
+  exit 1
+fi
+
+ORG_ID="$(prompt_with_default "$ORG_ID" "Org id (default: $ORG_ID): " "com.example")"
+FLUTTER_VERSION="$(prompt_with_default "$FLUTTER_VERSION" "Flutter version (default: $FLUTTER_VERSION): " "stable")"
+
+APP_PACKAGE_NAME="$(normalize_project_name "$PROJECT_NAME")"
+if [[ ! -d "$PARENT_DIR" ]]; then
+  echo "Error: parent directory does not exist: $PARENT_DIR" >&2
+  exit 1
+fi
+PARENT_DIR="$(cd "$PARENT_DIR" && pwd)"
+PROJECT_DIR="$PARENT_DIR/$PROJECT_NAME"
+
+if [[ -d "$PROJECT_DIR" ]] && [[ -n "$(ls -A "$PROJECT_DIR" 2>/dev/null || true)" ]] && [[ "$FORCE" -ne 1 ]]; then
+  echo "Error: '$PROJECT_DIR' exists and is not empty. Use --force to continue." >&2
+  exit 1
+fi
+
+echo "Bootstrapping project:"
+echo "- Directory: $PROJECT_DIR"
+echo "- App package name: $APP_PACKAGE_NAME"
+echo "- Org: $ORG_ID"
+echo "- Flutter version: $FLUTTER_VERSION"
+
+ensure_fvm
+
+mkdir -p "$PROJECT_DIR"
+cd "$PROJECT_DIR"
+
+fvm use "$FLUTTER_VERSION" --force
+
+create_args=(fvm flutter create . --org "$ORG_ID" --project-name "$APP_PACKAGE_NAME")
+if [[ "$FORCE" -eq 1 ]]; then
+  create_args+=(--overwrite)
+fi
+"${create_args[@]}"
+
+mkdir -p .vscode
+cat >.vscode/settings.json <<'JSON'
+{
+  "dart.flutterSdkPath": ".fvm/flutter_sdk",
+  "search.exclude": {
+    "**/.fvm": true
+  },
+  "files.watcherExclude": {
+    "**/.fvm": true
+  }
+}
+JSON
+
+fvm flutter pub add get flutter_bloc equatable dio retrofit json_annotation flutter_dotenv flutter_svg intl
+fvm flutter pub add --dev build_runner retrofit_generator json_serializable
+
+mkdir -p \
+  lib/src/api \
+  lib/src/core/managers \
+  lib/src/core/model/request \
+  lib/src/core/model/response \
+  lib/src/core/repository \
+  lib/src/di \
+  lib/src/enums \
+  lib/src/extensions \
+  lib/src/helper \
+  lib/src/locale \
+  lib/src/ui/base \
+  lib/src/ui/main \
+  lib/src/ui/home/binding \
+  lib/src/ui/home/bloc \
+  lib/src/ui/routing \
+  lib/src/ui/widgets \
+  lib/src/utils
+
+cat >lib/main.dart <<EOF
+import 'package:flutter/material.dart';
+import 'package:get/get.dart';
+
+import 'package:$APP_PACKAGE_NAME/src/di/di_graph_setup.dart';
+import 'package:$APP_PACKAGE_NAME/src/locale/translation_manager.dart';
+import 'package:$APP_PACKAGE_NAME/src/utils/app_pages.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await setupDependenciesGraph();
+  runApp(const App());
+}
+
+class App extends StatelessWidget {
+  const App({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return GetMaterialApp(
+      debugShowCheckedModeBanner: false,
+      initialRoute: AppPages.main,
+      getPages: AppPages.pages,
+      translations: TranslationManager(),
+      locale: TranslationManager.defaultLocale,
+      fallbackLocale: TranslationManager.fallbackLocale,
+    );
+  }
+}
+EOF
+
+cat >lib/src/di/di_graph_setup.dart <<'EOF'
+import 'environment_module.dart';
+import 'register_core_module.dart';
+import 'register_manager_module.dart';
+
+Future<void> setupDependenciesGraph() async {
+  await registerEnvironmentModule();
+  await registerCoreModule();
+  await registerManagerModule();
+}
+EOF
+
+cat >lib/src/di/environment_module.dart <<'EOF'
+import 'package:flutter_dotenv/flutter_dotenv.dart';
+
+Future<void> registerEnvironmentModule() async {
+  if (dotenv.isInitialized) return;
+  await dotenv.load(fileName: '.env');
+}
+EOF
+
+cat >lib/src/di/register_core_module.dart <<'EOF'
+Future<void> registerCoreModule() async {
+  // Register core services/repositories here.
+}
+EOF
+
+cat >lib/src/di/register_manager_module.dart <<'EOF'
+Future<void> registerManagerModule() async {
+  // Register app-wide managers here.
+}
+EOF
+
+cat >lib/src/utils/app_colors.dart <<'EOF'
+import 'package:flutter/material.dart';
+
+class AppColors {
+  AppColors._();
+
+  static const Color primary = Color(0xFF1F6FEB);
+  static const Color textPrimary = Color(0xFF1F2937);
+  static const Color white = Color(0xFFFFFFFF);
+}
+EOF
+
+cat >lib/src/utils/app_styles.dart <<'EOF'
+import 'package:flutter/material.dart';
+
+import 'app_colors.dart';
+
+class AppStyles {
+  AppStyles._();
+
+  static const TextStyle h1 = TextStyle(
+    fontSize: 24,
+    fontWeight: FontWeight.w700,
+    color: AppColors.textPrimary,
+  );
+}
+EOF
+
+cat >lib/src/utils/app_assets.dart <<'EOF'
+class AppAssets {
+  AppAssets._();
+
+  // Define image/icon paths here.
+}
+EOF
+
+cat >lib/src/utils/app_pages.dart <<EOF
+import 'package:get/get.dart';
+
+import 'package:$APP_PACKAGE_NAME/src/ui/home/binding/home_binding.dart';
+import 'package:$APP_PACKAGE_NAME/src/ui/home/home_page.dart';
+import 'package:$APP_PACKAGE_NAME/src/ui/main/main_page.dart';
+
+class AppPages {
+  AppPages._();
+
+  static const String main = '/';
+  static const String home = '/home';
+
+  static final List<GetPage<dynamic>> pages = <GetPage<dynamic>>[
+    GetPage(
+      name: main,
+      page: () => const MainPage(),
+      binding: HomeBinding(),
+    ),
+    GetPage(
+      name: home,
+      page: () => const HomePage(),
+      binding: HomeBinding(),
+    ),
+  ];
+}
+EOF
+
+cat >lib/src/locale/locale_key.dart <<'EOF'
+class LocaleKey {
+  LocaleKey._();
+
+  static const String homeTitle = 'home_title';
+}
+EOF
+
+cat >lib/src/locale/lang_en.dart <<'EOF'
+import 'locale_key.dart';
+
+final Map<String, String> enUs = <String, String>{
+  LocaleKey.homeTitle: 'Home',
+};
+EOF
+
+cat >lib/src/locale/lang_ja.dart <<'EOF'
+import 'locale_key.dart';
+
+final Map<String, String> jaJp = <String, String>{
+  LocaleKey.homeTitle: 'ホーム',
+};
+EOF
+
+cat >lib/src/locale/translation_manager.dart <<'EOF'
+import 'dart:ui';
+
+import 'package:get/get.dart';
+
+import 'lang_en.dart';
+import 'lang_ja.dart';
+
+class TranslationManager extends Translations {
+  static const Locale defaultLocale = Locale('en', 'US');
+  static const Locale fallbackLocale = Locale('en', 'US');
+  static const List<Locale> appLocales = <Locale>[
+    Locale('en', 'US'),
+    Locale('ja', 'JP'),
+  ];
+
+  @override
+  Map<String, Map<String, String>> get keys => <String, Map<String, String>>{
+        'en_US': enUs,
+        'ja_JP': jaJp,
+      };
+}
+EOF
+
+cat >lib/src/ui/main/main_page.dart <<EOF
+import 'package:flutter/material.dart';
+
+import 'package:$APP_PACKAGE_NAME/src/ui/home/home_page.dart';
+
+class MainPage extends StatelessWidget {
+  const MainPage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return const HomePage();
+  }
+}
+EOF
+
+cat >lib/src/ui/home/home_page.dart <<'EOF'
+import 'package:flutter/material.dart';
+import 'package:get/get.dart';
+
+import '../../locale/locale_key.dart';
+
+class HomePage extends StatelessWidget {
+  const HomePage({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: Text(LocaleKey.homeTitle.tr),
+      ),
+      body: Center(
+        child: Text(LocaleKey.homeTitle.tr),
+      ),
+    );
+  }
+}
+EOF
+
+cat >lib/src/ui/home/binding/home_binding.dart <<EOF
+import 'package:get/get.dart';
+
+import 'package:$APP_PACKAGE_NAME/src/ui/home/bloc/home_bloc.dart';
+
+class HomeBinding extends Bindings {
+  @override
+  void dependencies() {
+    if (!Get.isRegistered<HomeBloc>()) {
+      Get.lazyPut<HomeBloc>(HomeBloc.new);
+    }
+  }
+}
+EOF
+
+cat >lib/src/ui/home/bloc/home_bloc.dart <<'EOF'
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+class HomeBloc extends Cubit<int> {
+  HomeBloc() : super(0);
+}
+EOF
+
+cat >lib/src/ui/routing/home_router.dart <<EOF
+import 'package:flutter/material.dart';
+
+import 'package:$APP_PACKAGE_NAME/src/ui/home/home_page.dart';
+
+Route<dynamic> homeRouter(RouteSettings settings) {
+  return MaterialPageRoute<void>(
+    settings: settings,
+    builder: (_) => const HomePage(),
+  );
+}
+EOF
+
+cat >.env <<'EOF'
+API_BASE_URL=https://api.example.com
+EOF
+
+cat >.env.staging <<'EOF'
+API_BASE_URL=https://staging-api.example.com
+EOF
+
+cat >.env.prod <<'EOF'
+API_BASE_URL=https://api.example.com
+EOF
+
+ensure_line_in_file .gitignore ".env"
+ensure_line_in_file .gitignore ".env.staging"
+ensure_line_in_file .gitignore ".env.prod"
+
+if command -v fvm >/dev/null 2>&1; then
+  fvm dart format lib >/dev/null || true
+fi
+
+echo ""
+echo "Bootstrap completed."
+echo "Next steps:"
+echo "1) cd \"$PROJECT_DIR\""
+echo "2) fvm flutter run"