oh-my-customcodex 0.1.0

package/templates/guides/flutter/security.md

@@ -0,0 +1,120 @@
+# Flutter Security Guide
+
+> Reference: OWASP Mobile Top 10 (2024), Flutter Official Documentation
+
+## OWASP Mobile Top 10 Mapping
+
+### M1 — Improper Credential Usage
+
+- Never hardcode API keys, tokens, or credentials in source code
+- Backend proxy pattern: route ALL sensitive API calls through server
+- `--dart-define-from-file=.env` is for NON-SECRET build config only (values are extractable from binary)
+- Credential rotation: implement token refresh with `dio` interceptor
+- OAuth2 flow: use `flutter_appauth` for PKCE-based authentication
+
+### M2 — Inadequate Supply Chain Security
+
+- Run `dart pub audit` before every release to check for known vulnerabilities
+- Pin exact versions in `pubspec.yaml` for production (`package: 1.2.3` not `package: ^1.2.3`)
+- Verify package publisher on pub.dev (look for verified publisher badge)
+- Review transitive dependencies: `dart pub deps --style=compact`
+- Avoid packages with no recent updates (> 12 months without commits)
+
+### M3 — Insecure Authentication/Authorization
+
+- Biometric authentication: `local_auth` package with `BiometricType.fingerprint` / `BiometricType.face`
+- Session management: implement token expiry checking before API calls
+- JWT client-side validation: verify `exp`, `aud`, `iss` claims before using tokens
+- Re-authentication: require biometric/PIN for sensitive operations (payment, profile changes)
+- Deep link auth: validate authentication state before processing deep link navigation
+
+### M4 — Insufficient Input/Output Validation
+
+- Validate ALL deep link URI parameters with RegExp allowlists
+- Sanitize user input before displaying in WebView (`flutter_inappwebview`)
+- Use `Uri.parse()` with try-catch, never trust raw string URLs
+- Output encoding: escape HTML entities when rendering user content
+- Form validation: use `TextFormField` validators, never trust client-side validation alone
+
+### M5 — Insecure Communication
+
+- Certificate pinning (SPKI): use `dio` with custom `SecurityContext`
+- Extract SPKI hash: `openssl s_client -connect host:443 | openssl x509 -pubkey | openssl pkey -pubin -outform DER | openssl dgst -sha256 -binary | base64`
+- Include backup pins for certificate rotation
+- Android: `network_security_config.xml` with `cleartextTrafficPermitted=false`
+- iOS: ATS enabled (`NSAllowsArbitraryLoads=false`), never override in production
+
+### M6 — Inadequate Privacy Controls
+
+- Request minimum platform permissions (camera, location, contacts)
+- iOS: provide usage description strings in Info.plist for every permission
+- Android: use runtime permissions, respect "Don't ask again"
+- Data minimization: only collect and store data that is necessary
+- GDPR/CCPA: implement data export and deletion capabilities
+
+### M7 — Insufficient Binary Protections
+
+- Release builds: `flutter build --obfuscate --split-debug-info=debug-info/`
+- Store debug symbols securely for crash reporting (Crashlytics, Sentry)
+- Android ProGuard: configure `android/app/proguard-rules.pro`
+- Note: `--obfuscate` does NOT apply to `flutter build web` (JS minification is the web equivalent)
+- Anti-tampering: consider `flutter_jailbreak_detection` for integrity checks
+
+### M8 — Security Misconfiguration
+
+- Android: set `android:debuggable="false"` in release manifest
+- Android: set `android:allowBackup="false"` to prevent ADB data extraction
+- iOS: enable data protection with `NSFileProtectionComplete`
+- Remove all debug logging in release: guard with `kDebugMode`
+- Firebase: secure `google-services.json` / `GoogleService-Info.plist` (add to .gitignore)
+
+### M9 — Insecure Data Storage
+
+- Sensitive data: `flutter_secure_storage` v10+ (iOS Keychain / Android EncryptedSharedPreferences)
+- iOS: `IOSOptions(accessibility: KeychainAccessibility.first_unlock_this_device)`
+- Android: `AndroidOptions(encryptedSharedPreferences: true)`
+- Web WARNING: `flutter_secure_storage` uses localStorage on Web (XSS vulnerable) — use HttpOnly cookies or in-memory storage
+- Never use `SharedPreferences` for tokens, PII, or credentials
+- Screenshot protection: Android `FLAG_SECURE` via `flutter_windowmanager`
+
+### M10 — Insufficient Cryptography
+
+- Use `pointycastle` or `cryptography` package for custom crypto operations
+- Avoid: MD5, SHA-1, DES, ECB mode, hardcoded IVs/keys
+- Prefer: AES-256-GCM for symmetric, RSA-OAEP or ECDSA for asymmetric
+- Key storage: always delegate to platform Keychain/Keystore, never store in app data
+- Random number generation: use `Random.secure()` for security-sensitive values
+
+## Platform-Specific Security
+
+### iOS
+
+- Keychain with Secure Enclave: `IOSOptions(useSecureEnclave: true)` for high-value data
+- ATS enforcement: never add `NSAllowsArbitraryLoads` exception for production
+- Jailbreak detection: `flutter_jailbreak_detection` package
+
+### Android
+
+- Keystore-backed encryption via `EncryptedSharedPreferences`
+- Network security config: pin certificates, block cleartext
+- Root detection: `flutter_jailbreak_detection` or `safe_device`
+- `allowBackup=false` in AndroidManifest.xml
+
+### Web
+
+- CSP headers: configure on the server hosting Flutter web app
+- Avoid storing sensitive data in localStorage or sessionStorage
+- Use HttpOnly, Secure, SameSite cookies for authentication tokens
+- XSS prevention: sanitize all user-generated content before rendering
+
+## Package Recommendations
+
+| Category | Package | Notes |
+|----------|---------|-------|
+| Secure Storage | `flutter_secure_storage` | Keychain/Keystore, v10+; Web: localStorage (XSS risk) |
+| OAuth2 / PKCE | `flutter_appauth` | PKCE-based auth flows |
+| Biometrics | `local_auth` | Fingerprint, Face ID |
+| HTTP (pinning) | `dio` | Custom `SecurityContext` for certificate pinning |
+| Crypto | `cryptography` | AES-GCM, RSA-OAEP, ECDSA |
+| Integrity check | `flutter_jailbreak_detection` | Root/jailbreak detection |
+| Screenshot protect | `flutter_windowmanager` | Android `FLAG_SECURE` |

package/templates/guides/flutter/state-management.md

@@ -0,0 +1,144 @@
+# Flutter State Management
+
+> Reference: riverpod.dev, bloclibrary.dev, docs.flutter.dev/data-and-backend/state-mgmt
+
+## Selection Guide
+
+| Approach | Complexity | Scalability | Best For |
+|----------|-----------|-------------|----------|
+| **Riverpod 3.0** | Medium | Excellent | New projects (default) |
+| **BLoC 9.0** | High | Excellent | Enterprise, regulated industries |
+| **Provider** | Low | Moderate | Simple apps, learning |
+| **setState** | Low | Poor | Ephemeral local UI state |
+| **GetX** | Low | Poor | **AVOID** for new projects |
+
+## Riverpod 3.0 (Default)
+
+### Provider Types
+
+```dart
+// Simple value provider
+@riverpod
+String greeting(Ref ref) => 'Hello, World!';
+
+// Async data provider
+@riverpod
+Future<List<Product>> products(Ref ref) async {
+  final api = ref.watch(apiClientProvider);
+  return api.getProducts();
+}
+
+// Stateful notifier
+@riverpod
+class Counter extends _$Counter {
+  @override
+  int build() => 0;
+
+  void increment() => state++;
+  void decrement() => state--;
+}
+
+// Async stateful notifier
+@riverpod
+class ProductList extends _$ProductList {
+  @override
+  Future<List<Product>> build() async {
+    return ref.watch(productRepositoryProvider).getAll();
+  }
+
+  Future<void> addProduct(Product product) async {
+    await ref.read(productRepositoryProvider).add(product);
+    ref.invalidateSelf();
+  }
+}
+```
+
+### UI Consumption
+
+```dart
+class ProductListScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(productListProvider);
+
+    return state.when(
+      loading: () => const CircularProgressIndicator(),
+      error: (e, st) => Text('Error: $e'),
+      data: (products) => ListView.builder(
+        itemCount: products.length,
+        itemBuilder: (_, i) => ProductCard(products[i]),
+      ),
+    );
+  }
+}
+```
+
+### Key Rules
+
+- `ref.watch()` in build methods only (reactive)
+- `ref.read()` in callbacks and event handlers (one-time)
+- Never call `ref.watch()` inside non-build methods
+- Use `family` for parameterized providers
+- Use `keepAlive` sparingly (expensive computations only)
+
+## BLoC 9.0 (Enterprise)
+
+### Cubit (Simple)
+
+```dart
+class CounterCubit extends Cubit<int> {
+  CounterCubit() : super(0);
+
+  void increment() => emit(state + 1);
+  void decrement() => emit(state - 1);
+}
+
+// UI
+BlocBuilder<CounterCubit, int>(
+  builder: (context, count) => Text('$count'),
+)
+```
+
+### Bloc (Full Events)
+
+```dart
+// Events
+sealed class AuthEvent {}
+class LoginRequested extends AuthEvent {
+  final String email, password;
+  LoginRequested(this.email, this.password);
+}
+
+// States
+sealed class AuthState {}
+class AuthInitial extends AuthState {}
+class AuthLoading extends AuthState {}
+class AuthSuccess extends AuthState { final User user; AuthSuccess(this.user); }
+class AuthFailure extends AuthState { final String error; AuthFailure(this.error); }
+
+// Bloc
+class AuthBloc extends Bloc<AuthEvent, AuthState> {
+  AuthBloc(this._authRepo) : super(AuthInitial()) {
+    on<LoginRequested>(_onLogin);
+  }
+
+  final AuthRepository _authRepo;
+
+  Future<void> _onLogin(LoginRequested event, Emitter<AuthState> emit) async {
+    emit(AuthLoading());
+    final result = await _authRepo.login(event.email, event.password);
+    switch (result) {
+      case Ok(:final value): emit(AuthSuccess(value));
+      case Error(:final error): emit(AuthFailure(error.toString()));
+    }
+  }
+}
+```
+
+### Key Rules
+
+- One event per user action
+- Cubit for simple state, Bloc when audit trail needed
+- Never emit state in constructor
+- `BlocListener` for side effects, `BlocBuilder` for UI
+- Cancel subscriptions in `close()`

package/templates/guides/flutter/testing.md

@@ -0,0 +1,155 @@
+# Flutter Testing
+
+> Reference: docs.flutter.dev/testing/overview
+
+## Test Pyramid
+
+| Level | Speed | Confidence | Tool |
+|-------|-------|------------|------|
+| Unit | Fast | Low | `flutter_test` |
+| Widget | Fast | Medium | `testWidgets`, `WidgetTester` |
+| Integration | Slow | High | `integration_test` package |
+| Golden | Fast | Visual | `matchesGoldenFile()` |
+
+## Widget Tests (Primary)
+
+```dart
+testWidgets('ProductCard displays name and price', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      home: ProductCard(
+        product: Product(id: 1, name: 'Widget', price: 9.99),
+      ),
+    ),
+  );
+
+  expect(find.text('Widget'), findsOneWidget);
+  expect(find.text('\$9.99'), findsOneWidget);
+});
+
+testWidgets('tapping add button calls onAdd', (tester) async {
+  var called = false;
+  await tester.pumpWidget(
+    MaterialApp(
+      home: AddButton(onAdd: () => called = true),
+    ),
+  );
+
+  await tester.tap(find.byType(ElevatedButton));
+  expect(called, isTrue);
+});
+```
+
+## Riverpod Testing
+
+```dart
+testWidgets('ProductListScreen shows products', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        productListProvider.overrideWith(
+          () => FakeProductListNotifier(),
+        ),
+      ],
+      child: const MaterialApp(home: ProductListScreen()),
+    ),
+  );
+
+  await tester.pumpAndSettle();
+  expect(find.byType(ProductCard), findsNWidgets(3));
+});
+```
+
+## BLoC Testing
+
+```dart
+blocTest<CounterCubit, int>(
+  'increment emits [1] when initial state is 0',
+  build: () => CounterCubit(),
+  act: (cubit) => cubit.increment(),
+  expect: () => [1],
+);
+
+blocTest<AuthBloc, AuthState>(
+  'login emits [loading, success] on valid credentials',
+  build: () => AuthBloc(FakeAuthRepository()),
+  act: (bloc) => bloc.add(LoginRequested('user@test.com', 'pass123')),
+  expect: () => [
+    isA<AuthLoading>(),
+    isA<AuthSuccess>(),
+  ],
+);
+```
+
+## Mocking with mocktail
+
+```dart
+class MockProductRepository extends Mock implements ProductRepository {}
+
+void main() {
+  late MockProductRepository mockRepo;
+
+  setUp(() {
+    mockRepo = MockProductRepository();
+  });
+
+  test('getProducts returns list', () async {
+    when(() => mockRepo.getAll()).thenAnswer(
+      (_) async => Ok([Product(id: 1, name: 'Test', price: 9.99)]),
+    );
+
+    final result = await mockRepo.getAll();
+    expect(result, isA<Ok<List<Product>>>());
+  });
+}
+```
+
+## Golden Tests
+
+```dart
+testWidgets('ProductCard matches golden', (tester) async {
+  await tester.pumpWidget(
+    MaterialApp(
+      home: ProductCard(product: testProduct),
+    ),
+  );
+
+  await expectLater(
+    find.byType(ProductCard),
+    matchesGoldenFile('goldens/product_card.png'),
+  );
+});
+
+// Update goldens: flutter test --update-goldens
+```
+
+## Accessibility Testing
+
+```dart
+testWidgets('meets accessibility guidelines', (tester) async {
+  final handle = tester.ensureSemantics();
+  await tester.pumpWidget(const MaterialApp(home: MyScreen()));
+
+  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(textContrastGuideline));
+
+  handle.dispose();
+});
+```
+
+## Test Organization
+
+```
+test/
+├── unit/
+│   ├── repositories/product_repository_test.dart
+│   └── viewmodels/home_viewmodel_test.dart
+├── widget/
+│   ├── screens/product_list_screen_test.dart
+│   └── widgets/product_card_test.dart
+├── goldens/
+│   └── product_card.png
+integration_test/
+└── app_test.dart
+```

package/templates/guides/git-worktree-workflow/README.md

@@ -0,0 +1,138 @@
+# Git Worktree Workflow
+
+## Overview
+
+Git worktrees allow you to check out multiple branches simultaneously in separate directories, each with its own working tree. This eliminates the need to stash changes or commit incomplete work when switching between branches.
+
+**Key benefits:**
+- Work on `develop` and `team-plugin` simultaneously without context switching
+- Keep long-running feature branches open alongside hotfix branches
+- Run tests on one branch while coding on another
+
+## Recommended Directory Structure
+
+```
+~/workspace/projects/
+├── oh-my-customcodex/                   # Main worktree (develop)
+├── oh-my-customcodex-team-plugin/       # team-plugin branch
+└── oh-my-customcodex-release/           # release/* branches
+```
+
+Convention: `{repo-name}-{branch-suffix}` as sibling directories to the main worktree.
+
+## Basic Commands
+
+### Create a worktree
+
+```bash
+# From the main repository directory
+cd ~/workspace/projects/oh-my-customcodex
+
+# Attach to an existing remote branch
+git worktree add ../oh-my-customcodex-team-plugin team-plugin
+
+# Create a new branch and worktree together
+git worktree add ../oh-my-customcodex-release release/v0.43.0
+```
+
+### List worktrees
+
+```bash
+git worktree list
+```
+
+Output:
+```
+/Users/you/workspace/projects/oh-my-customcodex                abc1234 [develop]
+/Users/you/workspace/projects/oh-my-customcodex-team-plugin    def5678 [team-plugin]
+/Users/you/workspace/projects/oh-my-customcodex-release        ghi9012 [release/v0.43.0]
+```
+
+### Remove a worktree
+
+```bash
+# Remove after branch is merged
+git worktree remove ../oh-my-customcodex-release
+
+# Clean up stale worktree references
+git worktree prune
+```
+
+### Move a worktree
+
+```bash
+git worktree move ../oh-my-customcodex-release ../oh-my-customcodex-hotfix
+```
+
+## Runtime Integration
+
+### Built-in Worktree Tools
+
+The runtime provides `EnterWorktree` and `ExitWorktree` tools for session-scoped worktree management:
+
+```
+EnterWorktree(name: "feature-x")
+# Creates .claude/worktrees/feature-x with a new branch based on HEAD
+# Session working directory switches to the worktree
+
+EnterWorktree(path: "/absolute/path/to/existing-worktree")
+# Switches into an existing worktree of the current repository (v2.1.105+)
+# No new branch is created — uses the worktree as-is
+
+ExitWorktree()
+# Returns to the main repository
+# Prompts to keep or remove the worktree
+```
+
+### Agent Isolation Mode
+
+Agents can use `isolation: worktree` in their frontmatter to run in an isolated git worktree:
+
+```yaml
+---
+name: my-agent
+isolation: worktree
+---
+```
+
+This gives the agent a separate working copy, enabling safe code changes with rollback capability. The worktree is automatically created and cleaned up by the agent lifecycle.
+
+### Superpowers Skill
+
+The `superpowers` plugin includes a `using-git-worktrees` skill with additional patterns for worktree-based workflows. Reference it for advanced use cases like parallel CI testing and multi-branch refactoring.
+
+## Caveats
+
+### Same branch restriction
+
+A branch cannot be checked out in multiple worktrees simultaneously. Attempting this will fail:
+
+```bash
+# ERROR: 'develop' is already checked out at '~/workspace/projects/oh-my-customcodex'
+git worktree add ../oh-my-customcodex-dev2 develop
+```
+
+### Independent dependencies
+
+Each worktree has its own `node_modules`. Run package installation separately:
+
+```bash
+cd ../oh-my-customcodex-team-plugin
+bun install
+```
+
+### Gitignored files
+
+Files under `.claude/` are gitignored in this project. When adding new `.claude/` files, use `git add -f`:
+
+```bash
+git add -f .claude/agents/new-agent.md
+```
+
+### Shared git objects
+
+All worktrees share the same `.git` object store. Operations like `git gc` and `git fetch` affect all worktrees.
+
+### Worktree-local files
+
+Files listed in `.gitignore` (like `node_modules/`, `.env`) are independent per worktree. Configuration files that are not tracked must be set up separately in each worktree.

package/templates/guides/go-backend/index.yaml

@@ -0,0 +1,26 @@
+# Go Backend Guide
+
+metadata:
+  name: go-backend
+  description: Go backend development reference documentation
+
+source:
+  type: external
+  origin: various
+  urls:
+    - https://go.dev/doc/effective_go
+    - https://github.com/golang-standards/project-layout
+    - https://github.com/uber-go/guide/blob/master/style.md
+  last_fetched: "2026-01-22"
+
+documents:
+  - name: uber-style
+    path: ./uber-style.md
+    description: Uber Go style guide
+
+  - name: project-layout
+    path: ./project-layout.md
+    description: Standard Go project layout
+
+used_by:
+  - be-go-backend-expert