@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/architecture-designer/references/adr-template.md

@@ -0,0 +1,119 @@
+# ADR Template
+
+> Reference for: Architecture Designer
+> Load when: Documenting architectural decisions
+
+## ADR Format
+
+```markdown
+# ADR-{number}: {Title}
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[Describe the situation and forces at play. What is the problem?
+What constraints exist? What are we trying to achieve?]
+
+## Decision
+[State the decision clearly. What are we going to do?]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Neutral
+- [Side effect that is neither good nor bad]
+
+## Alternatives Considered
+[What other options were evaluated and why were they rejected?]
+
+## References
+- [Link to relevant documentation]
+- [Link to discussion/RFC]
+```
+
+## Example: Database Selection
+
+```markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+Accepted
+
+## Context
+We need a relational database for our e-commerce platform that:
+- Handles complex transactions with strong consistency
+- Supports JSON for flexible product attributes
+- Scales to millions of products and orders
+- Works well with our existing Python/Node stack
+
+Team has experience with PostgreSQL and MySQL.
+Budget allows for managed database service.
+
+## Decision
+Use PostgreSQL as the primary database, hosted on AWS RDS.
+
+## Consequences
+
+### Positive
+- ACID compliance for financial transactions
+- Rich feature set (JSON, full-text search, CTEs)
+- Strong community and tooling
+- Excellent performance with proper indexing
+- Free and open source
+
+### Negative
+- Vertical scaling has limits (addressed with read replicas)
+- Requires DBA expertise for optimization
+- AWS RDS costs for high availability
+
+### Neutral
+- Team will need to learn PostgreSQL-specific features
+- Migration from current SQLite dev database needed
+
+## Alternatives Considered
+
+**MySQL**
+- Rejected: Less feature-rich for JSON operations
+- Considered: Similar cost, familiar to team
+
+**MongoDB**
+- Rejected: Relational data model needed for orders/inventory
+- Considered: Great for product catalog flexibility
+
+**CockroachDB**
+- Rejected: Higher cost, team unfamiliar
+- Considered: Better horizontal scaling
+
+## References
+- https://www.postgresql.org/docs/current/
+- Internal RFC: Database Selection for E-commerce Platform
+```
+
+## ADR Naming Convention
+
+```
+docs/
+└── adr/
+    ├── 0001-use-postgresql-database.md
+    ├── 0002-adopt-microservices.md
+    ├── 0003-implement-event-sourcing.md
+    └── README.md
+```
+
+## Quick Reference
+
+| Section | Purpose | Key Question |
+|---------|---------|--------------|
+| Status | Current state | Is this active? |
+| Context | Background | Why are we deciding? |
+| Decision | The choice | What did we choose? |
+| Consequences | Impact | What happens now? |
+| Alternatives | Options | What else was considered? |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/architecture-designer/references/architecture-patterns.md

@@ -0,0 +1,114 @@
+# Architecture Patterns
+
+> Reference for: Architecture Designer
+> Load when: Choosing architecture approach
+
+## Pattern Comparison
+
+| Pattern | Best For | Team Size | Trade-offs |
+|---------|----------|-----------|------------|
+| **Monolith** | Simple domain, small team | 1-10 | Simple deploy; hard to scale parts |
+| **Modular Monolith** | Growing complexity | 5-20 | Module boundaries; still single deploy |
+| **Microservices** | Complex domain, large org | 20+ | Independent scale; operational complexity |
+| **Serverless** | Variable load, event-driven | Any | Auto-scale; cold starts, vendor lock |
+| **Event-Driven** | Async processing | 10+ | Loose coupling; debugging complexity |
+
+## Monolith
+
+```
+┌─────────────────────────────────────┐
+│            Application              │
+│  ┌─────┐  ┌─────┐  ┌─────┐         │
+│  │Users│  │Orders│ │Products│       │
+│  └─────┘  └─────┘  └─────┘         │
+│  └──────────┬──────────────┘        │
+│          Database                    │
+└─────────────────────────────────────┘
+```
+
+**When to Use**:
+- Starting a new project
+- Small team (< 10 developers)
+- Simple domain
+- Rapid iteration needed
+
+**Pros**: Simple deployment, easy debugging, no network latency
+**Cons**: Hard to scale independently, technology locked, deployment risk
+
+## Microservices
+
+```
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│  Users   │  │  Orders  │  │ Products │
+│ Service  │  │ Service  │  │ Service  │
+└────┬─────┘  └────┬─────┘  └────┬─────┘
+     │             │             │
+┌────▼────┐  ┌────▼────┐  ┌────▼────┐
+│ User DB │  │Order DB │  │ Prod DB │
+└─────────┘  └─────────┘  └─────────┘
+```
+
+**When to Use**:
+- Large team (20+ developers)
+- Complex domain with clear boundaries
+- Different scaling requirements per service
+- Polyglot technology needs
+
+**Pros**: Independent scaling, team autonomy, fault isolation
+**Cons**: Distributed system complexity, eventual consistency, operational overhead
+
+## Event-Driven
+
+```
+┌──────────┐     ┌─────────────┐     ┌──────────┐
+│ Producer │────▶│ Message Bus │────▶│ Consumer │
+└──────────┘     │  (Kafka)    │     └──────────┘
+                 └─────────────┘
+                       │
+                       ▼
+                 ┌──────────┐
+                 │ Consumer │
+                 └──────────┘
+```
+
+**When to Use**:
+- Async processing required
+- Loose coupling between services
+- Event sourcing needs
+- High throughput messaging
+
+**Pros**: Decoupled services, scalable, audit trail
+**Cons**: Eventual consistency, debugging complexity, message ordering
+
+## CQRS (Command Query Responsibility Segregation)
+
+```
+┌─────────┐         ┌─────────────┐
+│ Commands│────────▶│ Write Model │──┐
+└─────────┘         └─────────────┘  │
+                                     ▼
+                              ┌──────────┐
+                              │  Events  │
+                              └──────────┘
+                                     │
+┌─────────┐         ┌─────────────┐  │
+│ Queries │◀────────│ Read Model  │◀─┘
+└─────────┘         └─────────────┘
+```
+
+**When to Use**:
+- Read/write ratio heavily skewed
+- Complex read queries
+- Event sourcing architecture
+- Different optimization needs
+
+## Quick Reference
+
+| Requirement | Recommended Pattern |
+|-------------|---------------------|
+| Simple CRUD app | Monolith |
+| Growing startup | Modular Monolith |
+| Enterprise scale | Microservices |
+| Variable load | Serverless |
+| Async processing | Event-Driven |
+| Read-heavy | CQRS |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/architecture-designer/references/database-selection.md

@@ -0,0 +1,105 @@
+# Database Selection
+
+> Reference for: Architecture Designer
+> Load when: Choosing database technology
+
+## Database Types
+
+| Type | Examples | Best For |
+|------|----------|----------|
+| **Relational** | PostgreSQL, MySQL | Transactions, complex queries, relationships |
+| **Document** | MongoDB, Firestore | Flexible schemas, rapid iteration |
+| **Key-Value** | Redis, DynamoDB | Caching, sessions, high throughput |
+| **Time-Series** | TimescaleDB, InfluxDB | Metrics, IoT, analytics |
+| **Graph** | Neo4j, Neptune | Relationships, social networks |
+| **Search** | Elasticsearch, Meilisearch | Full-text search, logs |
+
+## Relational (PostgreSQL, MySQL)
+
+```
+Best For:
+- Financial transactions (ACID compliance)
+- Complex queries with joins
+- Data integrity requirements
+- Structured, predictable schemas
+
+When to Avoid:
+- Highly variable schemas
+- Massive horizontal scaling needs
+- Simple key-value access patterns
+```
+
+| Feature | PostgreSQL | MySQL |
+|---------|------------|-------|
+| JSON support | Excellent (JSONB) | Good (JSON) |
+| Full-text search | Built-in | Basic |
+| Extensions | Rich ecosystem | Limited |
+| Replication | Streaming, logical | Statement, row-based |
+
+## Document (MongoDB, Firestore)
+
+```
+Best For:
+- Flexible, evolving schemas
+- Hierarchical data (nested documents)
+- Rapid prototyping
+- Content management
+
+When to Avoid:
+- Complex transactions across documents
+- Heavy relational queries
+- Strict schema requirements
+```
+
+## Key-Value (Redis, DynamoDB)
+
+```
+Best For:
+- Session storage
+- Caching layer
+- Real-time leaderboards
+- Rate limiting counters
+
+When to Avoid:
+- Complex queries
+- Relational data
+- Large value sizes (>1MB)
+```
+
+## Time-Series (TimescaleDB, InfluxDB)
+
+```
+Best For:
+- Metrics and monitoring
+- IoT sensor data
+- Financial tick data
+- Event logging with timestamps
+
+When to Avoid:
+- Frequent updates to existing records
+- Complex relational queries
+- Non-time-based access patterns
+```
+
+## Decision Matrix
+
+| Requirement | Recommended |
+|-------------|-------------|
+| ACID transactions | PostgreSQL, MySQL |
+| Flexible schema | MongoDB, Firestore |
+| High-speed caching | Redis |
+| Time-series data | TimescaleDB, InfluxDB |
+| Social relationships | Neo4j |
+| Full-text search | Elasticsearch |
+| Serverless scale | DynamoDB, Firestore |
+
+## Quick Reference
+
+| Question | If Yes → |
+|----------|----------|
+| Need ACID transactions? | Relational (PostgreSQL) |
+| Schema changes frequently? | Document (MongoDB) |
+| Sub-millisecond reads? | Key-Value (Redis) |
+| Time-based queries? | Time-Series |
+| Traversing relationships? | Graph (Neo4j) |
+| Full-text search primary? | Elasticsearch |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/architecture-designer/references/nfr-checklist.md

@@ -0,0 +1,115 @@
+# Non-Functional Requirements Checklist
+
+> Reference for: Architecture Designer
+> Load when: Gathering system requirements
+
+## NFR Categories
+
+### Scalability
+
+| Question | Common Targets |
+|----------|----------------|
+| Expected concurrent users? | 100 / 1K / 10K / 100K |
+| Requests per second? | 10 / 100 / 1000 / 10000 |
+| Data volume? | GB / TB / PB |
+| Growth rate? | 10% / 50% / 100% per year |
+| Peak vs average load? | 2x / 5x / 10x |
+
+### Performance
+
+| Question | Common Targets |
+|----------|----------------|
+| API response time? | < 100ms / 200ms / 500ms p95 |
+| Page load time? | < 1s / 2s / 3s |
+| Database query time? | < 10ms / 50ms / 100ms |
+| Batch processing throughput? | 1K / 10K / 100K records/hour |
+
+### Availability
+
+| Target | Downtime/Year | Use Case |
+|--------|---------------|----------|
+| 99% | 3.65 days | Internal tools |
+| 99.9% | 8.76 hours | Business apps |
+| 99.95% | 4.38 hours | E-commerce |
+| 99.99% | 52.6 minutes | Financial systems |
+| 99.999% | 5.26 minutes | Life-critical |
+
+### Security
+
+| Question | Considerations |
+|----------|----------------|
+| Authentication required? | JWT, OAuth, SAML, MFA |
+| Authorization model? | RBAC, ABAC, ACL |
+| Data sensitivity? | Public, internal, confidential, PII |
+| Compliance requirements? | GDPR, HIPAA, PCI DSS, SOC 2 |
+| Encryption needs? | At rest, in transit, end-to-end |
+
+### Reliability
+
+| Question | Considerations |
+|----------|----------------|
+| Acceptable data loss? | RPO: 0 / 1hr / 24hr |
+| Recovery time target? | RTO: 1hr / 4hr / 24hr |
+| Backup frequency? | Real-time / hourly / daily |
+| Disaster recovery? | Single region / multi-region |
+
+### Maintainability
+
+| Question | Considerations |
+|----------|----------------|
+| Deployment frequency? | Daily / weekly / monthly |
+| Deployment strategy? | Blue-green, canary, rolling |
+| Monitoring requirements? | Logs, metrics, traces, alerts |
+| On-call requirements? | 24/7, business hours |
+
+### Cost
+
+| Question | Considerations |
+|----------|----------------|
+| Infrastructure budget? | $/month, $/user, $/request |
+| Operational budget? | FTE for maintenance |
+| Cost optimization? | Reserved instances, spot instances |
+| Cost alerts? | Thresholds for notification |
+
+## Template
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+- API response time: < 200ms p95
+- Page load time: < 2s
+- Database query time: < 50ms
+
+### Scalability
+- Concurrent users: 10,000
+- Requests per second: 1,000
+- Data volume: 1TB
+
+### Availability
+- Target: 99.9% (8.76 hours/year downtime)
+- RPO: 1 hour
+- RTO: 4 hours
+
+### Security
+- Authentication: JWT with refresh tokens
+- Authorization: Role-based (admin, user, guest)
+- Compliance: GDPR, SOC 2
+
+### Observability
+- Logging: Structured JSON to ELK
+- Metrics: Prometheus + Grafana
+- Tracing: OpenTelemetry
+- Alerts: PagerDuty integration
+```
+
+## Quick Reference
+
+| Category | Key Metric |
+|----------|------------|
+| Performance | Response time (p95) |
+| Scalability | Concurrent users, RPS |
+| Availability | Uptime percentage |
+| Reliability | RPO, RTO |
+| Security | Compliance requirements |
+| Cost | $/month budget |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/architecture-designer/references/system-design.md

@@ -0,0 +1,103 @@
+# System Design Template
+
+> Reference for: Architecture Designer
+> Load when: Designing new systems
+
+## Design Template
+
+```markdown
+# System: {System Name}
+
+## Requirements
+
+### Functional
+- [What the system must do]
+- [Core features and capabilities]
+
+### Non-Functional
+- **Performance**: Response time < 200ms p95
+- **Availability**: 99.9% uptime (8.76 hours downtime/year)
+- **Scalability**: Support 10,000 concurrent users
+- **Security**: PCI DSS compliance required
+
+### Constraints
+- Budget: $X/month for infrastructure
+- Timeline: MVP in 3 months
+- Team: 5 backend, 3 frontend engineers
+
+## High-Level Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Client    │────▶│  API Gateway │────▶│  Service    │
+│   (Web)     │     │   (Kong)    │     │  (Node.js)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                           │                   │
+                           ▼                   ▼
+                    ┌─────────────┐     ┌─────────────┐
+                    │    Auth     │     │  Database   │
+                    │  (Auth0)    │     │ (PostgreSQL)│
+                    └─────────────┘     └─────────────┘
+```
+
+## Component Details
+
+### API Layer
+- Technology: Node.js with Express/NestJS
+- Responsibilities: Request routing, validation, auth
+- Scaling: Horizontal via load balancer
+
+### Data Layer
+- Primary: PostgreSQL (transactions, relationships)
+- Cache: Redis (sessions, hot data)
+- Storage: S3 (files, images)
+
+### External Services
+- Auth: Auth0 (SSO, MFA)
+- Email: SendGrid (transactional)
+- Monitoring: Datadog (APM, logs)
+
+## Key Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| PostgreSQL over MongoDB | Relational data, ACID needed |
+| Redis for caching | Sub-ms latency required |
+| Auth0 over custom | Reduce security risk |
+
+## Scaling Strategy
+
+### Current (MVP)
+- Single region deployment
+- 2 API instances behind ALB
+- Single RDS instance
+
+### Future (10x growth)
+- Multi-region with CDN
+- Auto-scaling API (2-10 instances)
+- RDS read replicas
+
+## Security Considerations
+- All traffic over TLS 1.3
+- JWT tokens with 15-min expiry
+- Rate limiting: 100 req/min per user
+- WAF for common attacks
+
+## Failure Modes
+
+| Failure | Impact | Mitigation |
+|---------|--------|------------|
+| DB down | Full outage | Multi-AZ failover |
+| Cache down | Degraded perf | Fallback to DB |
+| Auth down | No new logins | Cache valid tokens |
+```
+
+## Quick Reference
+
+| Section | Key Questions |
+|---------|---------------|
+| Requirements | What must it do? How well? |
+| Architecture | What components? How connected? |
+| Decisions | Why these choices? |
+| Scaling | How to grow? |
+| Failures | What can break? How to recover? |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/ask-questions-if-underspecified/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ask-questions-if-underspecified
+description: Clarify requirements before implementing. Use when serious doubts arise.
+---
+
+# Ask Questions If Underspecified
+
+## When to Use
+
+Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.
+
+## When NOT to Use
+
+Do not use this skill when the request is already clear, or when a quick, low-risk discovery read can answer the missing details.
+
+## Goal
+
+Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
+
+## Workflow
+
+### 1) Decide whether the request is underspecified
+
+Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+- Define the objective (what should change vs stay the same)
+- Define "done" (acceptance criteria, examples, edge cases)
+- Define scope (which files/components/users are in/out)
+- Define constraints (compatibility, performance, style, deps, time)
+- Identify environment (language/runtime versions, OS, build/test runner)
+- Clarify safety/reversibility (data migration, rollout/rollback, risk)
+
+If multiple plausible interpretations exist, assume it is underspecified.
+
+### 2) Ask must-have questions first (keep it small)
+
+Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
+
+Make questions easy to answer:
+- Optimize for scannability (short, numbered questions; avoid paragraphs)
+- Offer multiple-choice options when possible
+- Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
+- Include a fast-path response (e.g., reply `defaults` to accept all recommended/default choices)
+- Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
+- Separate "Need to know" from "Nice to know" if that reduces friction
+- Structure options so the user can respond with compact decisions (e.g., `1b 2a 3c`); restate the chosen options in plain language to confirm
+
+### 3) Pause before acting
+
+Until must-have answers arrive:
+- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
+- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
+
+If the user explicitly asks you to proceed without answers:
+- State your assumptions as a short numbered list
+- Ask for confirmation; proceed only after they confirm or correct them
+
+### 4) Confirm interpretation, then proceed
+
+Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
+
+## Question templates
+
+- "Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
+- "Which of these should it be? A) ... B) ... C) ... (pick one)"
+- "What would you consider 'done'? For example: ..."
+- "Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
+- Use numbered questions with lettered options and a clear reply format
+
+```text
+1) Scope?
+a) Minimal change (default)
+b) Refactor while touching the area
+c) Not sure - use default
+2) Compatibility target?
+a) Current project defaults (default)
+b) Also support older versions: <specify>
+c) Not sure - use default
+
+Reply with: defaults (or 1a 2a)
+```
+
+## Anti-patterns
+
+- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
+- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.