@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/rust-engineer/references/traits.md

@@ -0,0 +1,413 @@
+# Traits, Generics, and Type System
+
+## Basic Trait Definition
+
+```rust
+// Simple trait
+trait Drawable {
+    fn draw(&self);
+}
+
+// Trait with default implementation
+trait Describable {
+    fn describe(&self) -> String {
+        String::from("No description available")
+    }
+}
+
+// Implementing traits
+struct Circle {
+    radius: f64,
+}
+
+impl Drawable for Circle {
+    fn draw(&self) {
+        println!("Drawing circle with radius {}", self.radius);
+    }
+}
+
+impl Describable for Circle {
+    fn describe(&self) -> String {
+        format!("A circle with radius {}", self.radius)
+    }
+}
+```
+
+## Associated Types
+
+```rust
+// Associated types vs generic parameters
+trait Container {
+    type Item;
+
+    fn add(&mut self, item: Self::Item);
+    fn get(&self, index: usize) -> Option<&Self::Item>;
+}
+
+impl Container for Vec<i32> {
+    type Item = i32;
+
+    fn add(&mut self, item: i32) {
+        self.push(item);
+    }
+
+    fn get(&self, index: usize) -> Option<&i32> {
+        self.get(index)
+    }
+}
+
+// Iterator trait (standard library example)
+trait MyIterator {
+    type Item;
+
+    fn next(&mut self) -> Option<Self::Item>;
+}
+```
+
+## Generic Traits and Bounds
+
+```rust
+// Generic trait with multiple bounds
+fn print_info<T>(item: &T)
+where
+    T: std::fmt::Display + std::fmt::Debug,
+{
+    println!("Display: {}", item);
+    println!("Debug: {:?}", item);
+}
+
+// Generic struct with trait bounds
+struct Pair<T: PartialOrd> {
+    first: T,
+    second: T,
+}
+
+impl<T: PartialOrd> Pair<T> {
+    fn new(first: T, second: T) -> Self {
+        Self { first, second }
+    }
+
+    fn larger(&self) -> &T {
+        if self.first > self.second {
+            &self.first
+        } else {
+            &self.second
+        }
+    }
+}
+
+// Blanket implementation
+trait MyTrait {
+    fn do_something(&self);
+}
+
+impl<T: std::fmt::Display> MyTrait for T {
+    fn do_something(&self) {
+        println!("Value: {}", self);
+    }
+}
+```
+
+## Trait Objects (Dynamic Dispatch)
+
+```rust
+// Static dispatch (monomorphization)
+fn static_dispatch<T: Drawable>(item: &T) {
+    item.draw();
+}
+
+// Dynamic dispatch (trait objects)
+fn dynamic_dispatch(item: &dyn Drawable) {
+    item.draw();
+}
+
+// Storing trait objects
+struct Canvas {
+    shapes: Vec<Box<dyn Drawable>>,
+}
+
+impl Canvas {
+    fn new() -> Self {
+        Self { shapes: Vec::new() }
+    }
+
+    fn add_shape(&mut self, shape: Box<dyn Drawable>) {
+        self.shapes.push(shape);
+    }
+
+    fn draw_all(&self) {
+        for shape in &self.shapes {
+            shape.draw();
+        }
+    }
+}
+
+// Object safety: traits must meet criteria
+trait ObjectSafe {
+    fn method(&self);  // OK: takes &self
+}
+
+trait NotObjectSafe {
+    fn generic<T>(&self);  // NOT OK: generic method
+    fn by_value(self);     // NOT OK: takes self by value
+}
+```
+
+## Derive Macros
+
+```rust
+// Standard derive macros
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+struct User {
+    id: u64,
+    name: String,
+}
+
+// Deriving more traits
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+struct Point {
+    x: i32,
+    y: i32,
+}
+
+// Custom derive with serde
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Serialize, Deserialize)]
+struct Config {
+    host: String,
+    port: u16,
+}
+```
+
+## Advanced Trait Patterns
+
+```rust
+// Extension trait pattern
+trait StringExt {
+    fn truncate_to(&self, max_len: usize) -> String;
+}
+
+impl StringExt for str {
+    fn truncate_to(&self, max_len: usize) -> String {
+        if self.len() <= max_len {
+            self.to_string()
+        } else {
+            format!("{}...", &self[..max_len])
+        }
+    }
+}
+
+// Sealed trait pattern (prevent external implementation)
+mod sealed {
+    pub trait Sealed {}
+}
+
+pub trait MySealed: sealed::Sealed {
+    fn method(&self);
+}
+
+struct MyType;
+impl sealed::Sealed for MyType {}
+impl MySealed for MyType {
+    fn method(&self) {
+        println!("Implemented");
+    }
+}
+
+// Supertraits
+trait Printable {
+    fn print(&self);
+}
+
+trait Loggable: Printable {  // Supertrait: must also impl Printable
+    fn log(&self) {
+        self.print();  // Can call supertrait methods
+    }
+}
+```
+
+## Associated Constants
+
+```rust
+trait Config {
+    const MAX_SIZE: usize;
+    const DEFAULT_TIMEOUT: u64;
+}
+
+struct ServerConfig;
+
+impl Config for ServerConfig {
+    const MAX_SIZE: usize = 1024;
+    const DEFAULT_TIMEOUT: u64 = 30;
+}
+
+fn use_config<T: Config>() {
+    println!("Max size: {}", T::MAX_SIZE);
+}
+```
+
+## Generic Associated Types (GATs)
+
+```rust
+// GATs allow generics in associated types
+trait LendingIterator {
+    type Item<'a> where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>>;
+}
+
+struct WindowsMut<'data, T> {
+    data: &'data mut [T],
+    index: usize,
+}
+
+impl<'data, T> LendingIterator for WindowsMut<'data, T> {
+    type Item<'a> = &'a mut [T] where Self: 'a;
+
+    fn next<'a>(&'a mut self) -> Option<Self::Item<'a>> {
+        if self.index >= self.data.len() {
+            return None;
+        }
+
+        let start = self.index;
+        self.index += 2;
+
+        Some(&mut self.data[start..start.min(self.data.len())])
+    }
+}
+```
+
+## Marker Traits
+
+```rust
+use std::marker::{PhantomData, Send, Sync};
+
+// Send: type can be transferred across thread boundaries
+// Sync: type can be shared between threads (&T is Send)
+
+// Custom marker trait
+trait Trusted {}
+
+struct TrustedData<T> {
+    data: T,
+    _marker: PhantomData<T>,
+}
+
+impl<T: Trusted> TrustedData<T> {
+    fn new(data: T) -> Self {
+        Self {
+            data,
+            _marker: PhantomData,
+        }
+    }
+}
+```
+
+## Operator Overloading
+
+```rust
+use std::ops::{Add, Mul};
+
+#[derive(Debug, Clone, Copy)]
+struct Vector2D {
+    x: f64,
+    y: f64,
+}
+
+impl Add for Vector2D {
+    type Output = Self;
+
+    fn add(self, other: Self) -> Self {
+        Self {
+            x: self.x + other.x,
+            y: self.y + other.y,
+        }
+    }
+}
+
+impl Mul<f64> for Vector2D {
+    type Output = Self;
+
+    fn mul(self, scalar: f64) -> Self {
+        Self {
+            x: self.x * scalar,
+            y: self.y * scalar,
+        }
+    }
+}
+
+// Usage
+let v1 = Vector2D { x: 1.0, y: 2.0 };
+let v2 = Vector2D { x: 3.0, y: 4.0 };
+let v3 = v1 + v2;
+let v4 = v1 * 2.5;
+```
+
+## From/Into Conversion Traits
+
+```rust
+struct UserId(u64);
+
+impl From<u64> for UserId {
+    fn from(id: u64) -> Self {
+        UserId(id)
+    }
+}
+
+// Into is automatically implemented
+fn accept_user_id(id: impl Into<UserId>) {
+    let user_id = id.into();
+    println!("User ID: {}", user_id.0);
+}
+
+// TryFrom for fallible conversions
+use std::convert::TryFrom;
+
+impl TryFrom<i64> for UserId {
+    type Error = &'static str;
+
+    fn try_from(value: i64) -> Result<Self, Self::Error> {
+        if value < 0 {
+            Err("User ID cannot be negative")
+        } else {
+            Ok(UserId(value as u64))
+        }
+    }
+}
+```
+
+## Const Traits (Nightly)
+
+```rust
+// Const trait implementations (requires nightly)
+#![feature(const_trait_impl)]
+
+#[const_trait]
+trait ConstAdd {
+    fn add(self, other: Self) -> Self;
+}
+
+impl const ConstAdd for i32 {
+    fn add(self, other: Self) -> Self {
+        self + other
+    }
+}
+
+const fn compute() -> i32 {
+    5.add(10)  // Can use in const context
+}
+```
+
+## Best Practices
+
+- Prefer associated types when there's one clear type per implementation
+- Use generic parameters when multiple types might be used simultaneously
+- Keep traits small and focused (single responsibility)
+- Use extension traits to add functionality to existing types
+- Document trait requirements and invariants
+- Use marker traits for compile-time guarantees
+- Prefer static dispatch for performance, dynamic dispatch for flexibility
+- Use #[derive] when possible instead of manual implementations
+- Implement standard traits (Debug, Clone, etc.) for better ecosystem integration
+- Use sealed traits to prevent external implementations when needed

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/rust-pro/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "rust-pro"
+description: "Use for modern Rust systems/services with stable 1.91-era patterns, async correctness, and performance-focused design."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "rust"
+  baseline: "Rust stable 1.91"
+---
+
+# Rust Pro
+
+## When to use
+
+- Building high-reliability services, CLIs, and systems components.
+- Solving ownership/lifetime design problems.
+- Optimizing memory safety and runtime performance together.
+
+## When not to use
+
+- Browser/frontend-only work with no Rust component.
+- Database-only tuning without Rust service or library changes.
+- Small scripts where shell or existing project tooling is the intended path.
+
+## Core workflow
+
+1. Define ownership and error model first.
+2. Choose async/runtime crates intentionally.
+3. Implement small composable modules.
+4. Verify with tests, clippy, and formatting.
+5. Profile before low-level optimization.
+
+## Baseline standards
+
+- `rustfmt` + `clippy` clean in CI.
+- Use explicit error types (`thiserror`/`anyhow` by layer).
+- Keep `unsafe` minimal and documented with invariants.
+- Prefer iterator/trait composition over macro-heavy complexity.
+- Make concurrency cancellation-safe and backpressure-aware.
+
+## Implementation guidance
+
+- Use `tokio`/`axum`/`tower` patterns for service work.
+- Model domain states with enums and exhaustive matching.
+- Use `Arc` + interior mutability only when ownership alternatives fail.
+- Keep borrow scopes tight to improve readability and compile times.
+- Separate transport DTOs from domain types.
+
+## Debugging and observability
+
+- Prefer reproducible failing tests and `tracing` instrumentation before redesigning ownership or async structure.
+- Make task cancellation, retries, and error chains visible in logs/telemetry.
+- Use `cargo test`, `clippy`, and targeted benchmarks to isolate regressions.
+
+## Performance and reliability
+
+- Keep async flows cancellation-safe and backpressure-aware.
+- Measure allocations, lock contention, and tail latency before unsafe or low-level tuning.
+- Bound work queues and connection pools explicitly.
+
+## References
+
+| File | Load when |
+| --- | --- |
+| `references/operational-baseline.md` | You need service-level guardrails for async, errors, tracing, and test discipline. |
+
+## Avoid
+
+- Premature `unsafe` optimization.
+- Silent `unwrap`/`expect` in non-test code paths.
+- Global mutable state for request data.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/rust-pro/references/operational-baseline.md

@@ -0,0 +1,9 @@
+## Operational baseline
+
+Load when: async service safety, tracing, error handling, or release guardrails need explicit guidance.
+
+- Keep error chains actionable and visible in logs/traces.
+- Use `cargo fmt`, `clippy`, and focused tests as a release baseline.
+- Make cancellation, queue bounds, and backpressure explicit.
+- Treat `unsafe` as an exception with documented invariants.
+- Profile before low-level optimization.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/saas-builder/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: "saas-builder"
+description: "Build or review production-ready multi-tenant SaaS systems on AWS serverless architecture with React + TypeScript frontend, tenant-isolated DynamoDB data models, JWT/RBAC authorization, Stripe subscriptions, and usage-based billing. Use for SaaS architecture design, implementation planning, API/Lambda patterns, billing workflows, and tenant isolation audits."
+---
+
+# SaaS Builder
+
+Implement multi-tenant SaaS systems with serverless-first architecture, strict tenant isolation, and billing-grade data handling.
+
+## Core Workflow
+
+1. Define tenant model, subscription tiers, quotas, and billable events before API design.
+2. Set repository layout using `steering/repository-structure.md`.
+3. Implement authentication first: Lambda authorizer, tenant claims, and role extraction.
+4. Implement tenant-scoped data access: all keys prefixed by tenant ID.
+5. Implement API endpoints with validation, RBAC checks, and tenant-aware logging.
+6. Implement billing integration: idempotent payment operations, webhook verification, usage metering.
+7. Implement frontend tenant context, quota handling, and feature-flagged UI.
+8. Validate cross-tenant isolation, billing edge cases, and operational monitoring before release.
+
+## Load Steering Files On Demand
+
+- `steering/architecture-principles.md`
+Purpose: Multi-tenancy, cost model, auth/authorization, compliance, and scalability constraints.
+Load when: Defining architecture decisions and non-functional requirements.
+
+- `steering/implementation-patterns.md`
+Purpose: API conventions, Lambda function sequence, DynamoDB keys, frontend/backend code style.
+Load when: Implementing endpoints, handlers, data access, and UI integration.
+
+- `steering/billing-and-payments.md`
+Purpose: Money representation, webhook/idempotency rules, subscription lifecycle, invoicing, tax, fraud, and testing.
+Load when: Implementing payments, usage metering, and financial reporting.
+
+- `steering/repository-structure.md`
+Purpose: Target monorepo layout and ownership boundaries for frontend/backend/schema/infrastructure.
+Load when: Bootstrapping or refactoring project structure.
+
+## Non-Negotiable Guardrails
+
+### Tenant Isolation
+
+- Read tenant ID only from authorizer claims, never from request body.
+- Prefix all partition keys with tenant context.
+- Reject any operation that can return cross-tenant data.
+- Enforce RBAC checks at function entry for sensitive operations.
+
+### Money and Billing
+
+- Store money as integer cents only.
+- Attach currency code to every monetary value.
+- Use idempotency keys for charge/refund/subscription mutations.
+- Verify webhook signatures and support retry-safe processing.
+
+### API and Lambda
+
+- Use versioned REST endpoints and proper HTTP status codes.
+- Validate request inputs at API boundary.
+- Keep handlers thin and move business logic into shared modules.
+- Log failures with tenant context while avoiding sensitive data leaks.
+
+### Security and Compliance
+
+- Use managed authentication providers (Cognito/Auth0).
+- Never store card numbers; use provider tokens only.
+- Encrypt data at rest and in transit.
+- Keep immutable financial audit trails.
+
+## MCP Setup
+
+Use `mcp.json` as baseline MCP configuration:
+
+- Set `AWS_PROFILE` and `AWS_REGION` for `awslabs.aws-serverless-mcp`.
+- Enable `stripe` (`"disabled": false`) when payment integration is required.
+- Enable `playwright` when browser automation tests are required.
+
+## Output Expectations
+
+When producing architecture or implementation deliverables, include:
+
+1. Tenant isolation strategy and key schema.
+2. API contract plan (or OpenAPI updates).
+3. Billing flow and failure-handling behavior.
+4. Security/compliance controls.
+5. Testing plan including cross-tenant leakage and billing edge cases.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/saas-builder/mcp.json

@@ -0,0 +1,51 @@
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-fetch"
+      ],
+      "env": {},
+      "disabled": false,
+      "autoApprove": []
+    },
+    "stripe": {
+      "url": "https://mcp.stripe.com",
+      "disabled": true
+    },
+    "aws-knowledge-mcp-server": {
+      "url": "https://knowledge-mcp.global.api.aws",
+      "disabled": false
+    },
+    "awslabs.dynamodb-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "awslabs.dynamodb-mcp-server@latest"
+      ],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": []
+    },
+    "awslabs.aws-serverless-mcp": {
+      "command": "uvx",
+      "args": [
+        "awslabs.aws-serverless-mcp-server@latest"
+      ],
+      "env": {
+        "AWS_PROFILE": "<PROFILE>",
+        "AWS_REGION": "<REGION>",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    },
+    "playwright": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@executeautomation/playwright-mcp-server"
+      ],
+      "disabled": true
+    }
+  }
+}

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/saas-builder/references/architecture-principles.md

@@ -0,0 +1,76 @@
+--- 
+inclusion: always 
+---
+
+# SaaS Architecture Principles
+
+## Multi-Tenancy First
+- Every data model MUST include tenant isolation (tenant_id prefix in all keys)
+- Prefix all entity keys with tenant: `pk: ${tenantId}#${entityType}#${id}`
+- Use separate tables per entity type, not single-table design
+- Never allow cross-tenant data access - validate tenant context on every operation
+- Tenant ID comes from Lambda authorizer JWT claims, never from request body
+- Design for tenant-level feature flags and configuration overrides
+- Plan for tenant-specific rate limits and quotas from day one
+
+## Cost-Per-Tenant Economics
+- Serverless-first: AWS Lambda, API Gateway, DynamoDB (on-demand), S3
+- Zero cost when idle - pay only for active tenant usage
+- Design for horizontal scaling: more tenants = same per-tenant cost
+- Avoid shared resources that don't scale linearly (RDS, fixed-size caches)
+- Use DynamoDB on-demand pricing until predictable traffic patterns emerge
+- Monitor cost per tenant to identify pricing model opportunities
+
+## Authentication & Authorization
+- Use managed auth: AWS Cognito or Auth0 (never roll your own)
+- JWT tokens with tenant claims and user roles embedded
+- Lambda authorizer validates tokens and injects tenant context + user roles
+- EVERY Lambda function MUST check user roles before performing operations
+- Role-based access control (RBAC) within tenants - check permissions at function entry
+- Never assume authorization - explicitly verify user has required role/permission
+- Support SSO/SAML for enterprise tenants
+- API keys for programmatic access with tenant scoping
+
+## Data Isolation & Compliance
+- Logical isolation via tenant_id (pool model) for cost efficiency
+- Physical isolation (separate tables/databases) only for enterprise tier
+- Encrypt at rest (DynamoDB encryption) and in transit (TLS)
+- Design for data residency requirements (multi-region support)
+- Audit logging per tenant for compliance (CloudTrail, custom audit tables)
+- Support tenant data export and deletion (GDPR, right to be forgotten)
+
+## Subscription & Billing Integration
+- Design features with usage metering from the start
+- Track billable events: API calls, storage, compute time, seats
+- Use EventBridge to publish usage events to billing system
+- Support multiple pricing tiers with feature gating
+- Plan for trial periods, freemium, and usage-based pricing
+- Graceful degradation when tenant exceeds quota or payment fails
+
+## Operational Excellence
+- Tenant-aware monitoring: CloudWatch metrics tagged by tenant_id
+- Isolate noisy neighbors: per-tenant rate limiting and circuit breakers
+- Feature flags for gradual rollout and A/B testing
+- Zero-downtime deployments with blue/green or canary
+- Tenant-specific health checks and status pages
+- Support tenant impersonation for debugging (with audit trail)
+
+## Scalability Patterns
+- Stateless services: no session affinity required
+- Async processing for heavy workloads (SQS, Step Functions)
+- Cache tenant config in Lambda memory (refresh on cold start)
+- Design for 10x growth: what breaks at 100 tenants? 1000? 10000?
+- Use DynamoDB GSIs for tenant-specific queries
+- Avoid fan-out queries across all tenants
+
+## Testing Strategy
+- Backend: Unit tests for business logic, integration tests for tenant isolation
+- Test cross-tenant data leakage scenarios explicitly
+- Load test with realistic multi-tenant traffic patterns
+- Frontend: Manual testing preferred, focus on tenant-specific UI variations
+
+## Dependency Management
+- Minimize third-party libraries - prefer AWS SDKs and built-in language features
+- Pin versions to avoid breakages
+- Prefer AWS-managed services over self-hosted alternatives
+- Evaluate libraries for multi-tenant safety (no global state)