OptiKit Flutter Development Assistant

This skill provides expert guidance for working with OptiKit CLI, a TypeScript-based command-line tool designed for Flutter developers using the Opticore micro framework. It automates module scaffolding, build processes, version management, and project maintenance tasks.

What This Skill Does

When invoked, this skill helps you:

1. Generate complete BLoC pattern modules for Opticore framework

2. Build and release APK, Bundle, IPA, and iOS packages

3. Manage version bumping across iOS and Android platforms

4. Clean Flutter projects and iOS-specific artifacts

5. Initialize and configure OptiKit settings

6. Set up VSCode workspace configurations

7. Open projects in Xcode or Android Studio

8. Manage automatic backups and rollbacks

Project Architecture Understanding

OptiKit uses a domain-based folder structure:

Step-by-Step Instructions

When User Asks About Module Generation

1. Explain that `optikit generate module <moduleName>` creates a complete BLoC structure:

- `bloc/` - BLoC implementation

- `event/` - Event definitions

- `state/` - State definitions

- `screen/` - UI screen widgets

- `factory/` - State factory

- `import/` - Centralized imports file

2. Mention class naming convention: snake_case module names convert to PascalCase (e.g., "user_profile" → "UserProfileBloc")

3. Note that generated files use `part of` syntax linking to central import file

When User Asks About Build Commands

1. List available build types:

- `optikit release-apk` - Android APK

- `optikit release-bundle` - Android App Bundle

- `optikit release-ipa` - iOS IPA (ad-hoc/enterprise)

- `optikit release-ios` - iOS for App Store

2. Explain FVM support: All commands support `--disable-fvm` flag

- Default: Uses `fvm` prefix for Flutter/Dart commands

- With flag: Uses global Flutter SDK

3. Mention pre-flight validation: All builds validate Flutter project structure, SDK installation, and platform-specific requirements

When User Asks About Version Management

1. Explain `optikit flutter-update-version` updates version across platforms:

- `pubspec.yaml` (version + build number)

- `ios/Runner.xcodeproj/project.pbxproj` (MARKETING_VERSION, CURRENT_PROJECT_VERSION)

- `ios/Runner/Info.plist` (CFBundleShortVersionString, CFBundleVersion)

- Runs `agvtool` commands for Xcode build settings

2. Describe version format: `X.Y.Z+B` (major.minor.patch+build)

3. Note automatic backup system creates timestamped backups in `.optikit-backup/`

When User Asks About iOS Build Issues

1. Explain retry pattern: iOS commands use 3 retries with 5s delay due to CocoaPods network instability

2. Note 10-minute timeout for pod operations

3. All iOS operations run in `ios/` directory via `execInIos()`

When User Wants to Add New Commands

1. Choose appropriate domain folder in `src/commands/` (build, clean, version, project, config)

2. Create command module in that folder (e.g., `src/commands/build/newBuild.ts`)

3. Import in `src/cli.ts` using `.js` extension (ES modules requirement)

4. Add `.command()` block with:

- Command signature and arguments

- Description text

- Options configuration (flags)

- Handler function calling module

5. Use categorized utilities:

- `LoggerHelpers` from `../utils/services/logger.js` for console output

- `execCommand()` from `../utils/services/exec.js` for shell operations

- `validateFlutterProject()` from `../utils/validators/validation.js` for validation

- `createBackup()` from `../utils/services/backup.js` for backups

When User Asks About Development Workflow

1. Provide essential commands:

```bash

npm install # Install dependencies

npm run build # Compile TypeScript to dist/

npm start # Run the CLI (after build)

```

2. Explain local testing:

```bash

npm link # Create global symlink

optikit <command> # Test commands globally

npm unlink # Remove symlink when done

```

3. Note direct execution: `node dist/cli.js`

Important Constraints

Configuration Management

OptiKit uses `.optikitrc.json` or `.optikitrc` configuration files with priority:

1. Project `.optikitrc`

2. Project `.optikitrc.json`

3. Home directory versions

Use `optikit config-init` to initialize configuration and `optikit rollback-last-change` for backup restoration.

Examples

**Generate a user profile module:**

```bash

optikit generate module user_profile

Creates: user_profile_bloc.dart, user_profile_event.dart, user_profile_state.dart, etc.

```

**Build Android APK with global Flutter:**

```bash

optikit release-apk --disable-fvm

```

**Update version to 2.1.0:**

```bash

optikit flutter-update-version --version 2.1.0+42

```

**Clean Flutter project:**

```bash

optikit clean-flutter

```