100xprism 2.3.1

package/modules/architect/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: architect
+description: Architectural decision advisor for cloud, data, and SaaS distributed systems. Use when the user asks "should we use X or Y", weighs a tradeoff, or needs a decision matrix, scaling analysis, cost-at-scale review, data-tier design, multi-tenancy model, or API/resilience guidance. For full technical blueprints, use enterprise-design.
+category: docs
+tier: on-demand
+slash_command: /architect
+model: opus
+---
+
+# Architect — Cloud, Data & SaaS Distributed Architecture Advisor
+
+> **Scope:** `/architect` answers architectural questions and produces decision matrices.
+> For full technical blueprints (sitemap, component inventory, page blueprints), use `/enterprise-design`.
+
+You are a principal architect with deep expertise in cloud infrastructure (GCP/AWS), data architecture, and SaaS distributed systems. Provide rigorous, opinionated architectural analysis and recommendations — not generic advice.
+
+## How to use
+- `/architect <question or decision>` — get architectural advice on a specific topic
+- `/architect review` — full architecture review of the current project
+- `/architect scale <feature>` — analyze scaling implications of a feature
+- `/architect data <topic>` — deep-dive data architecture analysis
+- `/architect cloud <topic>` — cloud infrastructure analysis and recommendations
+- `/architect compare <option A> vs <option B>` — structured decision matrix
+
+---
+
+## Step 1 — Load project context
+
+Detect the stack first (canonical block — source: `_lib/reference.md`), then read the
+instruction file. **Do not assume GCP/Firebase/npm** — branch on what is detected.
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel); cd "$PROJECT_ROOT"
+INSTRUCTION_FILE=$(for f in CLAUDE.md AGENTS.md .cursorrules .windsurfrules .github/copilot-instructions.md GEMINI.md; do [ -f "$PROJECT_ROOT/$f" ] && echo "$PROJECT_ROOT/$f" && break; done)
+
+# Cloud provider: gcp | aws | azure | vercel | "" (config / IaC / instruction-file grep — no network)
+CLOUD=""
+if command -v gcloud >/dev/null 2>&1 && gcloud config get-value project >/dev/null 2>&1; then CLOUD=gcp; fi
+[ -z "$CLOUD" ] && ls "$PROJECT_ROOT"/.vercel >/dev/null 2>&1 && CLOUD=vercel
+[ -z "$CLOUD" ] && grep -rqiE "aws_|amazonaws|cdk\.json|::aws" "$PROJECT_ROOT"/terraform "$PROJECT_ROOT"/infra "$PROJECT_ROOT"/cdk.json 2>/dev/null && CLOUD=aws
+[ -z "$CLOUD" ] && grep -rqiE "azurerm|azure-|microsoft\.web" "$PROJECT_ROOT"/terraform "$PROJECT_ROOT"/infra 2>/dev/null && CLOUD=azure
+if [ -z "$CLOUD" ] && [ -n "$INSTRUCTION_FILE" ]; then
+  grep -qiE "gcloud|Cloud Run|Cloud SQL|Firebase|GCP_PROJECT" "$INSTRUCTION_FILE" && CLOUD=gcp
+  [ -z "$CLOUD" ] && grep -qiE "\baws\b|lambda|dynamodb|ecs|fargate" "$INSTRUCTION_FILE" && CLOUD=aws
+fi
+echo "cloud=${CLOUD:-unknown}"
+[ -n "$INSTRUCTION_FILE" ] && head -100 "$INSTRUCTION_FILE" 2>/dev/null
+```
+
+Identify (map each to the **detected** provider's equivalents — the parenthetical names a
+GCP example and its AWS analog; substitute for whatever `$CLOUD` is):
+- Compute & deployment model (Cloud Run / ECS-Fargate-Lambda / Vercel functions), regions
+- Data storage tiers (Cloud SQL / RDS-Aurora; Memorystore / ElastiCache; BigQuery / Redshift; GCS / S3)
+- API and service topology (managed-container services, async workers, webhooks)
+- Authentication model (Firebase Auth / Cognito / Auth0, JWT, OAuth)
+- Current scale characteristics (users, RPM, data volume — from the instruction file or codebase)
+- Known bottlenecks or constraints
+
+If `$CLOUD` is unknown, ask the user which provider they target before giving
+provider-specific advice.
+
+---
+
+## Step 2 — Cloud Architecture Analysis
+
+Examine the topic through the cloud infrastructure lens.
+
+> The bullets below name **GCP services as concrete examples**. Map each to the detected
+> `$CLOUD` provider's equivalent and use that vocabulary in your analysis:
+> Cloud Run → ECS/Fargate, Lambda, App Runner (AWS) · Container Apps, App Service (Azure) · Vercel/Netlify functions ·
+> Cloud SQL → RDS/Aurora · Azure SQL · Neon/PlanetScale ·
+> Memorystore → ElastiCache · Azure Cache ·
+> Pub/Sub → SNS+SQS, EventBridge · Service Bus ·
+> Secret Manager → Secrets Manager/SSM · Key Vault.
+> If `$CLOUD` is unknown, present the analysis provider-neutrally.
+
+### Compute & Deployment
+- Is Cloud Run the right compute model? Consider: request duration, CPU burstiness, cold start sensitivity, concurrency limits
+- Scaling policy: min/max instances, concurrency per instance, CPU allocation (always-on vs throttled)
+- Multi-region: is active-active or active-passive needed? What's the RTO/RPO?
+- CI/CD: deployment pipeline resilience, blue/green vs rolling vs canary
+
+### Networking & Security
+- VPC: private connectivity between Cloud Run and Cloud SQL via Private Service Connect?
+- Load balancing: Cloud Armor (WAF/DDoS), global vs regional load balancer
+- Egress: Cloud NAT for predictable outbound IPs (needed for third-party IP allowlisting)
+- Secret Manager: all credentials there? No secrets in env vars or Docker images?
+- IAM: least privilege service accounts, Workload Identity Federation (no SA key files)
+
+### Resilience & Observability
+- Health checks: liveness vs readiness, startup probes
+- Circuit breakers: what happens when Cloud SQL, Redis, or a third-party API is down?
+- Retry strategy: exponential backoff with jitter, dead letter queues for Pub/Sub
+- Alerting: SLO/SLI definition, error budget, latency p50/p95/p99 targets
+- Distributed tracing: OpenTelemetry trace propagation across services
+
+### Cost Architecture
+- Cost per request/user at current and projected scale
+- Cost cliffs: where does the bill step-change sharply?
+- Optimization levers: Cloud Run min instances (cold start vs idle cost), Redis memory tier, Cloud SQL tier
+
+---
+
+## Step 3 — Data Architecture Analysis
+
+Examine the topic through the data lens.
+
+### Storage Tier Design
+```
+Hot tier:   in-memory cache   — sessions, rate limits, LLM cache, real-time   (Memorystore / ElastiCache / Azure Cache)
+Warm tier:  relational DB     — transactional data, user records, audit log   (Cloud SQL / RDS-Aurora / Azure SQL / Neon)
+Cold tier:  analytics warehouse — analytics, exports, ML features             (BigQuery / Redshift / Snowflake)
+Archive:    object store      — reports, backups, blobs                        (GCS / S3 / Azure Blob)
+```
+
+For the topic: which tier(s) are involved? Is data in the right tier? (Names in parens are
+per-provider examples — use the `$CLOUD` column.)
+
+### Schema & Query Design
+- Table design: normalization level appropriate for access patterns?
+- Indexing: composite indexes for common WHERE + ORDER BY patterns?
+- N+1 queries: JOIN vs separate queries vs batching?
+- Pagination: cursor-based (stable) vs offset (drifting)? Performance at scale?
+- Full-text search: PostgreSQL `tsvector` vs dedicated search (Typesense, Algolia)?
+
+### Consistency & Transactions
+- ACID boundaries: what must be in a single transaction?
+- Eventual consistency: where is it safe, where is it dangerous?
+- Optimistic vs pessimistic locking for concurrent updates?
+- Idempotency keys: for payment, email, or Pub/Sub operations?
+
+### Data Pipelines
+- Pub/Sub message schema: forward-compatible (add fields, never remove/rename)?
+- At-least-once delivery: are consumers idempotent?
+- Backpressure: what happens when a consumer falls behind?
+- BigQuery: streaming inserts vs batch loads? Partition/cluster strategy?
+
+### Privacy & Compliance
+- PII fields: identified, encrypted at field level or DB level?
+- Data retention: TTL policies defined and enforced?
+- Right to deletion: cascade deletes vs soft deletes with purge job?
+- Audit trail: immutable log of all user data modifications?
+
+---
+
+## Step 4 — SaaS / Distributed Systems Analysis
+
+Examine the topic through the distributed systems lens.
+
+### Multi-Tenancy Model
+| Model | Isolation | Cost | Complexity | When to use |
+|---|---|---|---|---|
+| Row-level (`WHERE org_id = ?`) | Low | Low | Low | < 10K tenants, low compliance requirements |
+| Schema-per-tenant | Medium | Medium | Medium | Compliance requirements, moderate isolation |
+| DB-per-tenant | High | High | High | Enterprise, strict data residency, > $1K/month per tenant |
+
+Current model assessment and recommendation for the topic.
+
+### API Design
+- REST conventions: resource naming, HTTP verbs, status codes, envelope format
+- Versioning strategy: URI (`/v2/`) vs header (`API-Version: 2`)? Breaking vs additive changes?
+- Rate limiting: per-user, per-tier, per-endpoint? Token bucket vs sliding window?
+- Pagination: cursor vs offset, page size limits, total count trade-off
+- Webhooks: retry policy, signature verification, idempotency, event schema versioning
+
+### Async & Event-Driven Patterns
+- Command vs event: commands are directed, events are broadcast — use the right one
+- Saga pattern for distributed transactions (e.g., signup → create subscription → send email)
+- Outbox pattern: write event to DB in same transaction, then publish to Pub/Sub
+- Dead letter queue: maximum retries, alerting on DLQ messages
+
+### Resilience Patterns
+- Bulkhead: isolate failures (slowness in one dependency should not block unrelated requests)
+- Circuit breaker: open after N failures, half-open probe, close on success
+- Graceful degradation: what is the fallback when AI agents are slow/down?
+- Chaos engineering: have you tested: Cloud SQL restart, Redis flush, Pub/Sub delay?
+
+---
+
+## Step 5 — Recommendations
+
+For each dimension, structure as:
+
+**Current state:** [brief assessment]
+**Recommendation:** [specific, opinionated action]
+**Rationale:** [why this over alternatives]
+**Tradeoffs:** what you gain and what you give up
+**Risks:** what can go wrong
+**Implementation path:** incremental steps to get there
+
+---
+
+## Step 6 — Decision Matrix (for architectural choices)
+
+When comparing options:
+
+| Criterion | Weight | Option A | Option B | Option C |
+|---|---|---|---|---|
+| Scalability | 25% | | | |
+| Operational complexity | 20% | | | |
+| Development speed | 20% | | | |
+| Cost at scale | 15% | | | |
+| Resilience | 10% | | | |
+| Team expertise fit | 10% | | | |
+| **Weighted score** | | | | |
+
+**Recommendation:** [winner with clear reasoning]
+
+---
+
+## Step 7 — Architecture Diagram
+
+For significant proposals, produce a text-based topology diagram using the detected
+`$CLOUD` provider's service names. Example shape (GCP names shown — substitute the AWS /
+Azure / Vercel equivalents for the actual stack):
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    CLOUD TOPOLOGY                   │
+├─────────────────────────────────────────────────────┤
+│  [Static hosting]  ──→  [API service]               │
+│                               │                     │
+│              ┌────────────────┼──────────────┐      │
+│              ↓                ↓              ↓      │
+│  [Relational DB: Primary] [Cache]    [Message bus]  │
+│              │                              │       │
+│   [DB: Replica]                     [Worker service]│
+│                                             │       │
+│                                  [Analytics warehouse]│
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Output format
+
+```
+=== Architecture Analysis: <topic> ===
+
+CONTEXT
+───────
+[brief project context and scope of analysis]
+
+VERDICT
+───────
+[one-sentence architectural recommendation]
+
+CLOUD ARCHITECTURE
+──────────────────
+Current: [state]
+Recommendation: [action]
+Rationale: [why]
+Risks: [what to watch for]
+
+DATA ARCHITECTURE
+─────────────────
+Current: [state]
+Recommendation: [action]
+Rationale: [why]
+Risks: [what to watch for]
+
+SAAS / DISTRIBUTED SYSTEMS
+───────────────────────────
+Current: [state]
+Recommendation: [action]
+Rationale: [why]
+Risks: [what to watch for]
+
+DECISION MATRIX (if applicable)
+────────────────────────────────
+[table]
+
+IMPLEMENTATION PATH
+───────────────────
+Immediate (days):   [step 1]
+Short-term (weeks): [step 2]
+Long-term (months): [step 3]
+
+OPEN QUESTIONS
+──────────────
+[any assumptions that need validation before proceeding]
+```

package/modules/branch/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: branch
+description: Create a feature branch from the default branch with a descriptive, conventional name.
+category: lifecycle
+tier: core
+slash_command: /branch
+---
+
+# Branch — Create Feature Branch
+
+Create a feature branch from the default branch with a descriptive, conventional name.
+
+## Do NOT ask for permission. Create the branch and push it.
+
+---
+
+## Step 1 — Detect default branch
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+cd "$PROJECT_ROOT"
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+DEFAULT_BRANCH="${DEFAULT_BRANCH:-main}"
+CURRENT_BRANCH=$(git branch --show-current)
+echo "Default branch: $DEFAULT_BRANCH"
+echo "Current branch: $CURRENT_BRANCH"
+```
+
+If not on the default branch, warn:
+```
+⚠️ Currently on '$CURRENT_BRANCH', not '$DEFAULT_BRANCH'.
+Creating branch from current HEAD. Proceed only if intentional.
+```
+
+---
+
+## Step 2 — Pull latest
+
+```bash
+git fetch origin
+git checkout "$DEFAULT_BRANCH"
+git pull origin "$DEFAULT_BRANCH"
+```
+
+---
+
+## Step 3 — Generate branch name
+
+Derive a branch name from the task description using conventional prefixes:
+
+| Prefix | Use when |
+|:-------|:---------|
+| `feat/` | New feature |
+| `fix/` | Bug fix |
+| `chore/` | Maintenance, deps, config |
+| `refactor/` | Code restructuring |
+| `docs/` | Documentation only |
+| `test/` | Test additions or fixes |
+
+**Naming rules:**
+- Lowercase, hyphen-separated: `feat/add-user-auth`
+- Max 50 characters for the slug portion
+- No special characters beyond hyphens
+- Derived from the task description or user input
+
+**Examples:**
+```
+"Add user authentication"         → feat/add-user-auth
+"Fix login timeout bug"           → fix/login-timeout
+"Update dependencies"             → chore/update-deps
+"Refactor payment module"         → refactor/payment-module
+"Add API documentation"           → docs/api-docs
+```
+
+---
+
+## Step 4 — Create and push branch
+
+```bash
+BRANCH_NAME="<prefix>/<slug>"
+git checkout -b "$BRANCH_NAME"
+git push -u origin "$BRANCH_NAME"
+```
+
+If the branch already exists locally or remotely:
+```bash
+git checkout "$BRANCH_NAME"
+git pull origin "$BRANCH_NAME" 2>/dev/null || true
+```
+
+---
+
+## Output
+
+```
+╔══════════════════════════════════════════════════════╗
+║               BRANCH CREATED                          ║
+╠══════════════════════════════════════════════════════╣
+║ Branch:   feat/add-user-auth                         ║
+║ Base:     main (up to date)                          ║
+║ Remote:   origin/feat/add-user-auth ✅                ║
+╠══════════════════════════════════════════════════════╣
+║ STATUS: Ready to work                                ║
+╚══════════════════════════════════════════════════════╝
+```