@cubis/foundry 0.3.30 → 0.3.32

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: "postman"
+description: "Automate API testing and collection management with Postman - create workspaces, collections, environments, and run tests programmatically"
+---
+
+
+# Onboarding
+
+Before proceeding, validate that the user has completed the following steps before using this power.
+
+## Step 1
+
+Generate and maintain `cbx_config.json` as the only Postman configuration source (workspace: `./cbx_config.json`, global: `~/.cbx/cbx_config.json`). Use named profiles in `postman.profiles` and choose `postman.activeProfileName`. Use env-first authentication by default: keep `apiKey` as `null`, set `apiKeyEnvVar` to `POSTMAN_API_KEY` (or another profile alias), and read the key from environment variables. Only store `apiKey` inline when the user explicitly requests file-based key storage. Keep workspace selection in the active profile `workspaceId` (`null` when unknown).
+
+## Step 2
+
+Create a hook that runs anytime the source code or configuration file has been changed. Save the hook in .kiro/hooks/hookname.kiro.hook. Example hook format. Please update the patterns to match the project's file structure.
+
+```json
+{
+  "enabled": true,
+  "name": "API Postman Testing",
+  "description": "Monitors API source code changes across multiple programming languages and automatically runs Postman collection tests to validate functionality",
+  "version": "1",
+  "when": {
+    "type": "fileEdited",
+    "patterns": [
+      "*.js",
+      "*.ts",
+      "*.py",
+      "*.java",
+      "*.cs",
+      "*.go", 
+      "*.rs",
+      "*.php",
+      "*.rb",
+      "*.kt",
+      "*.swift",
+      "*.scala",
+      "package.json",
+      "requirements.txt",
+      "Pipfile",
+      "pom.xml",
+      "build.gradle",
+      "*.csproj",
+      "go.mod",
+      "Cargo.toml",
+      "composer.json",
+      "Gemfile",
+      "build.sbt",
+      "openapi.yaml",
+      "openapi.yml",
+      "swagger.yaml",
+      "swagger.yml",
+      "api.yaml",
+      "api.yml"
+    ]
+  },
+  "then": {
+    "type": "askAgent",
+    "prompt": "API source code or configuration has been modified. Please retrieve the contents of the .postman.json file. If the file does not exist or is empty, create a Postman collection for the API. If it exists, get the collection ID and run the collection, showing me the results and propose fixes for any errors found."
+  }
+}
+```
+# Overview
+
+Automate API testing and collection management with Postman. Create workspaces, collections, environments, and run tests programmatically.
+
+**Authentication**: Env-first via `cbx_config.json` + profile env alias (default `POSTMAN_API_KEY`); inline `apiKey` is optional.
+
+## Available MCP Servers
+
+### postman
+**Package:** `@postman/postman-mcp-server`
+**Connection:** SSE-based MCP server
+**Authentication:** Postman API key via Bearer token
+**Mode:** Minimal (40 essential tools) - Default configuration
+**Endpoint:** https://mcp.postman.com/minimal
+
+**Note:** This power connects to Postman's hosted MCP server via SSE. To enable Full mode (112 tools) for advanced collaboration and enterprise features, change the URL to `https://mcp.postman.com/full`.
+
+**Available Tools (40 in Minimal Mode):**
+
+**Workspace Management:**
+- `createWorkspace` - Create a new workspace
+- `getWorkspace` - Get workspace details
+- `getWorkspaces` - List all accessible workspaces
+- `updateWorkspace` - Update workspace properties
+
+**Collection Management:**
+- `createCollection` - Create a new API collection
+- `getCollection` - Get detailed collection information
+- `getCollections` - List all collections in a workspace
+- `putCollection` - Replace/update entire collection
+- `duplicateCollection` - Create a copy of a collection
+- `createCollectionRequest` - Add a request to a collection
+- `createCollectionResponse` - Add a response example to a request
+
+**Environment Management:**
+- `createEnvironment` - Create a new environment
+- `getEnvironment` - Get environment details
+- `getEnvironments` - List all environments
+- `putEnvironment` - Replace/update entire environment
+
+**Mock Server Management:**
+- `createMock` - Create a mock server
+- `getMock` - Get mock server details
+- `getMocks` - List all mock servers
+- `updateMock` - Update mock server configuration
+- `publishMock` - Make mock server public
+
+**API Specification Management:**
+- `createSpec` - Create a new API specification
+- `getSpec` - Get specification details
+- `getAllSpecs` - List all specifications
+- `getSpecDefinition` - Get complete spec definition
+- `updateSpecProperties` - Update spec metadata
+- `createSpecFile` - Add a file to a spec
+- `getSpecFile` - Get a specific spec file
+- `getSpecFiles` - List all files in a spec
+- `updateSpecFile` - Update a spec file
+
+**Code Generation & Sync:**
+- `generateCollection` - Generate collection from API spec
+- `generateSpecFromCollection` - Generate spec from collection
+- `getGeneratedCollectionSpecs` - Get specs generated from a collection
+- `getSpecCollections` - Get collections generated from a spec
+- `syncCollectionWithSpec` - Sync collection with its spec
+- `syncSpecWithCollection` - Sync spec with its collection
+
+**Testing & Execution:**
+- `runCollection` - Execute a collection with automated tests
+
+**User & Metadata:**
+- `getAuthenticatedUser` - Get current user information
+- `getTaggedEntities` - Get entities by tag
+- `getStatusOfAnAsyncApiTask` - Check async task status
+- `getEnabledTools` - List available tools by mode
+
+## Tool Usage Examples
+
+```javascript
+// Create workspace
+mcp_postman_createWorkspace({
+  "workspace": { "name": "My API Project", "type": "personal" }
+})
+
+// Create collection
+mcp_postman_createCollection({
+  "workspace": "workspace-id",
+  "collection": {
+    "info": {
+      "name": "User API",
+      "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+    }
+  }
+})
+
+// Create environment
+mcp_postman_createEnvironment({
+  "workspace": "workspace-id",
+  "environment": {
+    "name": "Local",
+    "values": [
+      { "key": "base_url", "value": "http://localhost:3000", "enabled": true }
+    ]
+  }
+})
+
+// Run collection
+mcp_postman_runCollection({
+  "collectionId": "collection-id",
+  "environmentId": "environment-id"
+})
+```
+
+## Workflows
+
+**Project Setup:**
+```javascript
+const { workspace } = await mcp_postman_createWorkspace({ "workspace": { "name": "Project", "type": "personal" }})
+const { collection } = await mcp_postman_createCollection({ "workspace": workspace.id, "collection": { "info": { "name": "API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }}})
+const { environment } = await mcp_postman_createEnvironment({ "workspace": workspace.id, "environment": { "name": "Local", "values": [{ "key": "base_url", "value": "http://localhost:3000", "enabled": true }]}})
+// Save IDs to .postman.json
+```
+
+**Generate from OpenAPI:**
+```javascript
+const { spec } = await mcp_postman_createSpec({ "workspaceId": "workspace-id", "name": "API Spec", "type": "OPENAPI:3.0", "files": [{ "path": "openapi.yaml", "content": "..." }]})
+const result = await mcp_postman_generateCollection({ "specId": spec.id, "elementType": "collection", "name": "Generated Collection" })
+```
+
+**Automated Testing:**
+```javascript
+const { workspaces } = await mcp_postman_getWorkspaces()
+const { collections } = await mcp_postman_getCollections({ "workspace": workspaces[0].id })
+const { environments } = await mcp_postman_getEnvironments({ "workspace": workspaces[0].id })
+for (const collection of collections) {
+  await mcp_postman_runCollection({ "collectionId": collection.uid, "environmentId": environments[0]?.id })
+}
+```
+
+## Best Practices
+
+- Store workspace/collection/environment IDs in `.postman.json`
+- Use environment variables for different contexts (local/staging/production)
+- Add post-request test scripts for validation
+- Organize requests in folders
+- Run collections before deployment
+- Ensure API server is running before tests
+
+## Troubleshooting
+
+**"Collection not found"**: Call `getCollections` to verify ID and permissions
+
+**"Environment not found"**: Call `getEnvironments` with correct workspace ID
+
+**Test failures**: Verify API server running, check environment variables (base_url, api_key), review test scripts
+
+**"Invalid API key"**: Generate new key at postman.com Settings → API Keys, verify permissions
+
+## Configuration
+
+**MCP Configuration (Minimal mode - 40 tools):**
+```json
+{
+  "mcpServers": {
+    "postman": {
+      "url": "https://mcp.postman.com/minimal",
+      "headers": {
+        "Authorization": "Bearer ${POSTMAN_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Full mode (112 tools):** Change URL to `https://mcp.postman.com/full`
+
+**API Key Permissions:** Workspace management, collection read/write, environment read/write, collection runs

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/POWER.md

@@ -0,0 +1,89 @@
+---
+name: "flutter-expert"
+displayName: "Flutter Expert"
+description: "Flutter development with Riverpod 3, GoRouter, and Clean Architecture"
+keywords:
+  [
+    "flutter",
+    "riverpod",
+    "gorouter",
+    "dart",
+    "widget",
+    "provider",
+    "state",
+    "navigation",
+    "async",
+  ]
+---
+
+# Flutter Expert
+
+## Onboarding
+
+Verify Flutter is installed:
+
+```bash
+flutter --version
+```
+
+## When to Load Steering Files
+
+- Working with Riverpod providers → `riverpod-state.md`
+- Navigation/routing → `gorouter-navigation.md`
+- Widget patterns → `widget-patterns.md`
+- Project structure → `project-structure.md`
+- Performance optimization → `performance.md`
+- Engineering principles → `engineering-principles.md`
+
+## Related Specialized Powers
+
+For deeper expertise in specific areas, activate these powers:
+
+- **riverpod-3** - Advanced Riverpod patterns (caching, paging, testing)
+- **gorouter-restoration** - Routing, guards, deep links, state restoration
+- **accessibility** - WCAG compliance, semantics, screen readers
+- **ux-ui-consistency** - Screen states, design system components, UX patterns
+- **error-ux-observability** - Error handling, logging, user feedback
+- **flutter-security-reviewer** - Secure storage, network security, PII protection
+- **flutter-code-reviewer** - Architecture review, performance, testing
+- **design-system-builder** - Creating/updating design system components
+
+## Quick Reference
+
+### Riverpod 3 Provider Pattern
+
+```dart
+@riverpod
+class FeatureNotifier extends _$FeatureNotifier {
+  @override
+  FutureOr<State> build() async => fetchData();
+
+  Future<void> update() async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() => api.update());
+  }
+}
+```
+
+### Consumer Widget
+
+```dart
+class MyScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(featureNotifierProvider);
+    return state.when(
+      data: (data) => Content(data),
+      loading: () => const CircularProgressIndicator(),
+      error: (e, st) => ErrorWidget(error: e),
+    );
+  }
+}
+```
+
+### Key Rules
+
+- Use `ref.watch()` in build, `ref.read()` in callbacks
+- Use `ref.mounted` after async operations
+- Run `flutter pub run build_runner build -d` after provider changes
+- Use `Ref` (not typed refs like `AutoDisposeRef`)

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: "flutter-expert"
+description: "Flutter development with Riverpod 3, GoRouter, and Clean Architecture"
+---
+
+
+# Flutter Expert
+
+## Onboarding
+
+Verify Flutter is installed:
+
+```bash
+flutter --version
+```
+
+## When to Load Steering Files
+
+- Working with Riverpod providers → `riverpod-state.md`
+- Navigation/routing → `gorouter-navigation.md`
+- Widget patterns → `widget-patterns.md`
+- Project structure → `project-structure.md`
+- Performance optimization → `performance.md`
+- Engineering principles → `engineering-principles.md`
+
+## Related Specialized Powers
+
+For deeper expertise in specific areas, activate these powers:
+
+- **riverpod-3** - Advanced Riverpod patterns (caching, paging, testing)
+- **gorouter-restoration** - Routing, guards, deep links, state restoration
+- **accessibility** - WCAG compliance, semantics, screen readers
+- **ux-ui-consistency** - Screen states, design system components, UX patterns
+- **error-ux-observability** - Error handling, logging, user feedback
+- **flutter-security-reviewer** - Secure storage, network security, PII protection
+- **flutter-code-reviewer** - Architecture review, performance, testing
+- **design-system-builder** - Creating/updating design system components
+
+## Quick Reference
+
+### Riverpod 3 Provider Pattern
+
+```dart
+@riverpod
+class FeatureNotifier extends _$FeatureNotifier {
+  @override
+  FutureOr<State> build() async => fetchData();
+
+  Future<void> update() async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() => api.update());
+  }
+}
+```
+
+### Consumer Widget
+
+```dart
+class MyScreen extends ConsumerWidget {
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final state = ref.watch(featureNotifierProvider);
+    return state.when(
+      data: (data) => Content(data),
+      loading: () => const CircularProgressIndicator(),
+      error: (e, st) => ErrorWidget(error: e),
+    );
+  }
+}
+```
+
+### Key Rules
+
+- Use `ref.watch()` in build, `ref.read()` in callbacks
+- Use `ref.mounted` after async operations
+- Run `flutter pub run build_runner build -d` after provider changes
+- Use `Ref` (not typed refs like `AutoDisposeRef`)

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/postman/flutter-expert/references/bloc-state.md

@@ -0,0 +1,259 @@
+# Bloc State Management
+
+## When to Use Bloc
+
+Use **Bloc/Cubit** when you need:
+
+* Explicit event → state transitions
+* Complex business logic
+* Predictable, testable flows
+* Clear separation between UI and logic
+
+| Use Case               | Recommended |
+| ---------------------- | ----------- |
+| Simple mutable state   | Riverpod    |
+| Event-driven workflows | Bloc        |
+| Forms, auth, wizards   | Bloc        |
+| Feature modules        | Bloc        |
+
+---
+
+## Core Concepts
+
+| Concept | Description            |
+| ------- | ---------------------- |
+| Event   | User/system input      |
+| State   | Immutable UI state     |
+| Bloc    | Event → State mapper   |
+| Cubit   | State-only (no events) |
+
+---
+
+## Basic Bloc Setup
+
+### Event
+
+```dart
+sealed class CounterEvent {}
+
+final class CounterIncremented extends CounterEvent {}
+
+final class CounterDecremented extends CounterEvent {}
+```
+
+### State
+
+```dart
+class CounterState {
+  final int value;
+
+  const CounterState({required this.value});
+
+  CounterState copyWith({int? value}) {
+    return CounterState(value: value ?? this.value);
+  }
+}
+```
+
+### Bloc
+
+```dart
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+class CounterBloc extends Bloc<CounterEvent, CounterState> {
+  CounterBloc() : super(const CounterState(value: 0)) {
+    on<CounterIncremented>((event, emit) {
+      emit(state.copyWith(value: state.value + 1));
+    });
+
+    on<CounterDecremented>((event, emit) {
+      emit(state.copyWith(value: state.value - 1));
+    });
+  }
+}
+```
+
+---
+
+## Cubit (Recommended for Simpler Logic)
+
+```dart
+class CounterCubit extends Cubit<int> {
+  CounterCubit() : super(0);
+
+  void increment() => emit(state + 1);
+  void decrement() => emit(state - 1);
+}
+```
+
+---
+
+## Providing Bloc to the Widget Tree
+
+```dart
+BlocProvider(
+  create: (_) => CounterBloc(),
+  child: const CounterScreen(),
+);
+```
+
+Multiple blocs:
+
+```dart
+MultiBlocProvider(
+  providers: [
+    BlocProvider(create: (_) => AuthBloc()),
+    BlocProvider(create: (_) => ProfileBloc()),
+  ],
+  child: const AppRoot(),
+);
+```
+
+---
+
+## Using Bloc in Widgets
+
+### BlocBuilder (UI rebuilds)
+
+```dart
+class CounterScreen extends StatelessWidget {
+  const CounterScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<CounterBloc, CounterState>(
+      buildWhen: (prev, curr) => prev.value != curr.value,
+      builder: (context, state) {
+        return Text(
+          state.value.toString(),
+          style: Theme.of(context).textTheme.displayLarge,
+        );
+      },
+    );
+  }
+}
+```
+
+---
+
+### BlocListener (Side Effects)
+
+```dart
+BlocListener<AuthBloc, AuthState>(
+  listenWhen: (prev, curr) => curr is AuthFailure,
+  listener: (context, state) {
+    if (state is AuthFailure) {
+      ScaffoldMessenger.of(context)
+          .showSnackBar(SnackBar(content: Text(state.message)));
+    }
+  },
+  child: const LoginForm(),
+);
+```
+
+---
+
+### BlocConsumer (Builder + Listener)
+
+```dart
+BlocConsumer<FormBloc, FormState>(
+  listener: (context, state) {
+    if (state.status == FormStatus.success) {
+      context.pop();
+    }
+  },
+  builder: (context, state) {
+    return ElevatedButton(
+      onPressed: state.isValid
+          ? () => context.read<FormBloc>().add(FormSubmitted())
+          : null,
+      child: const Text('Submit'),
+    );
+  },
+);
+```
+
+---
+
+## Accessing Bloc Without Rebuilds
+
+```dart
+context.read<CounterBloc>().add(CounterIncremented());
+```
+
+⚠️ **Never use `watch` inside callbacks**
+
+---
+
+## Async Bloc Pattern (API Calls)
+
+```dart
+on<UserRequested>((event, emit) async {
+  emit(const UserState.loading());
+
+  try {
+    final user = await repository.fetchUser();
+    emit(UserState.success(user));
+  } catch (e) {
+    emit(UserState.failure(e.toString()));
+  }
+});
+```
+
+---
+
+## Bloc + GoRouter (Auth Guard Example)
+
+```dart
+redirect: (context, state) {
+  final authState = context.read<AuthBloc>().state;
+
+  if (authState is Unauthenticated) {
+    return '/login';
+  }
+  return null;
+}
+```
+
+---
+
+## Testing Bloc
+
+```dart
+blocTest<CounterBloc, CounterState>(
+  'emits incremented value',
+  build: () => CounterBloc(),
+  act: (bloc) => bloc.add(CounterIncremented()),
+  expect: () => [
+    const CounterState(value: 1),
+  ],
+);
+```
+
+---
+
+## Best Practices (MUST FOLLOW)
+
+✅ Immutable states
+✅ Small, focused blocs
+✅ One feature = one bloc
+✅ Use Cubit when possible
+✅ Test all blocs
+
+❌ No UI logic inside blocs
+❌ No context usage inside blocs
+❌ No mutable state
+❌ No massive “god blocs”
+
+---
+
+## Quick Reference
+
+| Widget            | Purpose              |
+| ----------------- | -------------------- |
+| BlocBuilder       | UI rebuild           |
+| BlocListener      | Side effects         |
+| BlocConsumer      | Both                 |
+| BlocProvider      | Dependency injection |
+| MultiBlocProvider | Multiple blocs       |
+