@cubis/foundry 0.3.70 → 0.3.72

package/workflows/powers/serverless-patterns/POWER.md

@@ -0,0 +1,171 @@
+````markdown
+---
+inclusion: manual
+name: serverless-patterns
+description: Design serverless architectures with Lambda, Edge Functions, event-driven patterns, cold start optimization, and cost management strategies.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Serverless Patterns
+
+## Purpose
+
+Guide serverless architecture design and implementation. Covers function design, event-driven patterns, cold start optimization, edge computing, cost management, and common pitfalls.
+
+## When to Use
+
+- Designing serverless applications (Lambda, Cloud Functions, Edge Functions)
+- Choosing between serverless and traditional server architectures
+- Optimizing cold starts and execution time
+- Implementing event-driven workflows (queues, streams, triggers)
+- Managing costs and avoiding serverless anti-patterns
+- Building API backends with serverless functions
+
+## Instructions
+
+### Step 1 — Choose the Right Compute Model
+
+| Model                                            | Best For                                | Latency                | Cost Model                |
+| ------------------------------------------------ | --------------------------------------- | ---------------------- | ------------------------- |
+| AWS Lambda / Cloud Functions                     | Event-driven, variable load             | Cold start: 100ms-2s   | Per-invocation + duration |
+| Edge Functions (Cloudflare Workers, Vercel Edge) | Low latency, geographically distributed | < 50ms (no cold start) | Per-request               |
+| Long-running containers (ECS, Cloud Run)         | Steady load, WebSockets, > 15 min tasks | No cold start          | Per-second                |
+
+**Serverless fits when**:
+
+- Traffic is bursty or unpredictable
+- Functions complete in < 30 seconds
+- Stateless request/response pattern
+- Event-driven processing (queue consumers, webhooks)
+
+**Serverless doesn't fit when**:
+
+- Persistent connections (WebSockets, long polling)
+- Heavy computation (> 15 min)
+- Steady high-throughput workloads (always-on is cheaper)
+- Complex local state management
+
+### Step 2 — Design Functions
+
+**Single-responsibility**: one function per operation
+
+```
+api/
+├── users/
+│   ├── create.ts      (POST /users)
+│   ├── get.ts         (GET /users/:id)
+│   └── list.ts        (GET /users)
+├── orders/
+│   ├── create.ts      (POST /orders)
+│   └── process.ts     (SQS consumer)
+└── shared/
+    ├── db.ts           (connection pooling)
+    └── auth.ts         (token validation)
+```
+
+**Rules**:
+
+- Keep functions small (< 200 lines)
+- Initialize expensive resources outside the handler (connection pools, SDK clients)
+- Handle one event type per function
+- Return early for validation failures
+
+### Step 3 — Optimize Cold Starts
+
+**Cold start happens when**:
+
+- First invocation after deployment
+- Scaling up to handle more concurrent requests
+- Function hasn't been invoked for ~15 minutes
+
+**Optimization strategies**:
+| Strategy | Impact |
+|----------|--------|
+| Smaller bundle size | Fewer bytes to load = faster start |
+| Fewer dependencies | Less initialization code |
+| Lazy-load non-critical modules | Only import what the handler needs |
+| Provisioned concurrency | Pre-warm instances (costs more) |
+| Edge functions | No cold start (Cloudflare Workers) |
+| Choose lighter runtimes | Node.js > Python > Java for cold start |
+
+**Connection pooling**:
+
+```typescript
+// Initialize OUTSIDE the handler (reused across invocations)
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 1 });
+
+export async function handler(event) {
+  const client = await pool.connect();
+  try {
+    // use client
+  } finally {
+    client.release(); // return to pool, don't close
+  }
+}
+```
+
+### Step 4 — Event-Driven Patterns
+
+| Pattern              | Use Case                               | Services                           |
+| -------------------- | -------------------------------------- | ---------------------------------- |
+| Queue consumer       | Decoupled async processing             | SQS, Cloud Tasks                   |
+| Fan-out              | Parallel processing of events          | SNS + Lambda, EventBridge          |
+| Saga / Step Function | Multi-step workflows with compensation | Step Functions, Temporal           |
+| CRON                 | Scheduled tasks                        | EventBridge rules, Cloud Scheduler |
+| Stream processing    | Real-time event processing             | Kinesis, Kafka                     |
+| Webhook receiver     | Third-party event handling             | API Gateway + Lambda               |
+
+**Error handling in async functions**:
+
+- Use dead-letter queues (DLQ) for failed messages
+- Implement idempotency (same message processed twice = same result)
+- Retry with exponential backoff
+- Alert on DLQ depth
+
+### Step 5 — Manage Costs
+
+**Cost drivers**:
+
+- Number of invocations
+- Execution duration × memory allocated
+- Data transfer (egress)
+- Provisioned concurrency (if used)
+
+**Optimization**:
+
+- Right-size memory (sometimes more memory = faster = cheaper)
+- Minimize execution time (return early, batch operations)
+- Use reserved concurrency to cap costs
+- Compress responses to reduce data transfer
+- Monitor with cost allocation tags
+
+## Output Format
+
+```
+## Architecture
+[serverless design with function layout and event flows]
+
+## Implementation
+[function code with cold start optimization]
+
+## Infrastructure
+[IaC for deployment (CDK, Terraform, serverless.yml)]
+
+## Cost Estimate
+[projected costs based on expected traffic]
+```
+
+## Examples
+
+**User**: "Build a serverless API for our mobile app"
+
+**Response approach**: API Gateway + Lambda per endpoint. JWT auth at the gateway. DynamoDB or RDS Proxy for data. Optimize cold starts with minimal dependencies. Show CDK or Serverless Framework config.
+
+**User**: "Our Lambda functions have 3-second cold starts"
+
+**Response approach**: Audit bundle size and dependencies. Lazy-load non-critical modules. Move initialization outside handler. Consider provisioned concurrency for latency-sensitive functions. Evaluate edge functions for the hottest paths.
+````

package/workflows/powers/serverless-patterns/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: serverless-patterns
+description: Design serverless architectures with Lambda, Edge Functions, event-driven patterns, cold start optimization, and cost management strategies.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot, Gemini CLI
+---
+
+# Serverless Patterns
+
+## Purpose
+
+Guide serverless architecture design and implementation. Covers function design, event-driven patterns, cold start optimization, edge computing, cost management, and common pitfalls.
+
+## When to Use
+
+- Designing serverless applications (Lambda, Cloud Functions, Edge Functions)
+- Choosing between serverless and traditional server architectures
+- Optimizing cold starts and execution time
+- Implementing event-driven workflows (queues, streams, triggers)
+- Managing costs and avoiding serverless anti-patterns
+- Building API backends with serverless functions
+
+## Instructions
+
+### Step 1 — Choose the Right Compute Model
+
+| Model                                            | Best For                                | Latency                | Cost Model                |
+| ------------------------------------------------ | --------------------------------------- | ---------------------- | ------------------------- |
+| AWS Lambda / Cloud Functions                     | Event-driven, variable load             | Cold start: 100ms-2s   | Per-invocation + duration |
+| Edge Functions (Cloudflare Workers, Vercel Edge) | Low latency, geographically distributed | < 50ms (no cold start) | Per-request               |
+| Long-running containers (ECS, Cloud Run)         | Steady load, WebSockets, > 15 min tasks | No cold start          | Per-second                |
+
+**Serverless fits when**:
+
+- Traffic is bursty or unpredictable
+- Functions complete in < 30 seconds
+- Stateless request/response pattern
+- Event-driven processing (queue consumers, webhooks)
+
+**Serverless doesn't fit when**:
+
+- Persistent connections (WebSockets, long polling)
+- Heavy computation (> 15 min)
+- Steady high-throughput workloads (always-on is cheaper)
+- Complex local state management
+
+### Step 2 — Design Functions
+
+**Single-responsibility**: one function per operation
+
+```
+api/
+├── users/
+│   ├── create.ts      (POST /users)
+│   ├── get.ts         (GET /users/:id)
+│   └── list.ts        (GET /users)
+├── orders/
+│   ├── create.ts      (POST /orders)
+│   └── process.ts     (SQS consumer)
+└── shared/
+    ├── db.ts           (connection pooling)
+    └── auth.ts         (token validation)
+```
+
+**Rules**:
+
+- Keep functions small (< 200 lines)
+- Initialize expensive resources outside the handler (connection pools, SDK clients)
+- Handle one event type per function
+- Return early for validation failures
+
+### Step 3 — Optimize Cold Starts
+
+**Cold start happens when**:
+
+- First invocation after deployment
+- Scaling up to handle more concurrent requests
+- Function hasn't been invoked for ~15 minutes
+
+**Optimization strategies**:
+| Strategy | Impact |
+|----------|--------|
+| Smaller bundle size | Fewer bytes to load = faster start |
+| Fewer dependencies | Less initialization code |
+| Lazy-load non-critical modules | Only import what the handler needs |
+| Provisioned concurrency | Pre-warm instances (costs more) |
+| Edge functions | No cold start (Cloudflare Workers) |
+| Choose lighter runtimes | Node.js > Python > Java for cold start |
+
+**Connection pooling**:
+
+```typescript
+// Initialize OUTSIDE the handler (reused across invocations)
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 1 });
+
+export async function handler(event) {
+  const client = await pool.connect();
+  try {
+    // use client
+  } finally {
+    client.release(); // return to pool, don't close
+  }
+}
+```
+
+### Step 4 — Event-Driven Patterns
+
+| Pattern              | Use Case                               | Services                           |
+| -------------------- | -------------------------------------- | ---------------------------------- |
+| Queue consumer       | Decoupled async processing             | SQS, Cloud Tasks                   |
+| Fan-out              | Parallel processing of events          | SNS + Lambda, EventBridge          |
+| Saga / Step Function | Multi-step workflows with compensation | Step Functions, Temporal           |
+| CRON                 | Scheduled tasks                        | EventBridge rules, Cloud Scheduler |
+| Stream processing    | Real-time event processing             | Kinesis, Kafka                     |
+| Webhook receiver     | Third-party event handling             | API Gateway + Lambda               |
+
+**Error handling in async functions**:
+
+- Use dead-letter queues (DLQ) for failed messages
+- Implement idempotency (same message processed twice = same result)
+- Retry with exponential backoff
+- Alert on DLQ depth
+
+### Step 5 — Manage Costs
+
+**Cost drivers**:
+
+- Number of invocations
+- Execution duration × memory allocated
+- Data transfer (egress)
+- Provisioned concurrency (if used)
+
+**Optimization**:
+
+- Right-size memory (sometimes more memory = faster = cheaper)
+- Minimize execution time (return early, batch operations)
+- Use reserved concurrency to cap costs
+- Compress responses to reduce data transfer
+- Monitor with cost allocation tags
+
+## Output Format
+
+```
+## Architecture
+[serverless design with function layout and event flows]
+
+## Implementation
+[function code with cold start optimization]
+
+## Infrastructure
+[IaC for deployment (CDK, Terraform, serverless.yml)]
+
+## Cost Estimate
+[projected costs based on expected traffic]
+```
+
+## Examples
+
+**User**: "Build a serverless API for our mobile app"
+
+**Response approach**: API Gateway + Lambda per endpoint. JWT auth at the gateway. DynamoDB or RDS Proxy for data. Optimize cold starts with minimal dependencies. Show CDK or Serverless Framework config.
+
+**User**: "Our Lambda functions have 3-second cold starts"
+
+**Response approach**: Audit bundle size and dependencies. Lazy-load non-critical modules. Move initialization outside handler. Consider provisioned concurrency for latency-sensitive functions. Evaluate edge functions for the hottest paths.

package/workflows/powers/skill-creator/POWER.md

@@ -0,0 +1,90 @@
+````markdown
+---
+inclusion: manual
+name: skill-creator
+description: Create, test, improve, and package portable AI skills using the Agent Skills SKILL.md format across Claude Code, Codex, and GitHub Copilot, with Gemini conversion when needed. Use this when the user wants to build, repair, benchmark, or iterate on a reusable skill package.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Skill Creator
+
+## Purpose
+
+Create and improve reusable AI skill packages with a human-in-the-loop loop: define the skill, draft it, test it with the skill enabled, evaluate results qualitatively and quantitatively, rewrite based on signal, and repeat until the package is good enough to scale.
+
+## When to Use
+
+- The user wants to create a new skill package under `workflows/skills/<name>`.
+- The user wants to repair or modernize an existing `SKILL.md` package.
+- The user wants evals, benchmarks, or review tooling for a skill package.
+- The user wants to package one canonical skill for Claude Code, Codex, GitHub Copilot, and optionally Gemini.
+
+## Instructions
+
+1. Decide what the skill should do before writing files. Confirm the task boundary, activation phrases, expected outputs, supported platforms, and whether the skill needs objective evals.
+
+2. Write a first draft of the skill package. Keep one canonical `SKILL.md` as the source of truth. Add sidecars only when they reduce prompt bloat or remove repeated work.
+
+3. Create a small test set first. Add a few realistic prompts to `evals/` and keep them representative of the skill's actual use cases, not just ideal happy paths.
+
+4. Run the skill with the skill enabled on the test prompts. Prefer Claude with access to the skill for the first qualitative pass so you can inspect whether the instructions actually trigger the right behavior.
+
+5. While runs are happening, draft or refine the quantitative evals. If quantitative evals already exist, review them, keep the ones that are still useful, and adjust only the ones that no longer match the intended behavior.
+
+6. Explain the evals to the user before over-optimizing against them. The user should understand what each prompt, assertion, or benchmark is measuring and what a pass or fail means.
+
+7. Review the outputs both qualitatively and quantitatively. Use `eval-viewer/generate_review.py` so the user can inspect side-by-side outputs and benchmark summaries instead of relying only on raw JSON.
+
+8. Rewrite the skill based on user feedback and the strongest benchmark signal. Fix root causes, not just individual failing prompts, and treat obvious flaws in the quantitative results as design feedback for the skill.
+
+9. Repeat the loop until the results are stable enough. Keep iterating until the user is satisfied or the skill behavior has clearly plateaued.
+
+10. Expand the test set and rerun at larger scale only after the small-set loop is working. Do not scale weak evals or unclear instructions.
+
+11. Use the right script for the job:
+    - `scripts/run_loop.py` is the original Claude-oriented optimization loop built on `run_eval.py`.
+    - `scripts/run_loop_universal.py` is the portable loop built on `run_eval_universal.py` and `platform_adapter.py`.
+    - Prefer the universal loop when the package is intended to stay portable across Claude Code, Codex, Copilot, and Gemini-style workflows.
+
+## Output Format
+
+Produce a canonical skill package with:
+
+- a valid root `SKILL.md`
+- any needed `references/`, `scripts/`, `assets/`, `evals/`, and `eval-viewer/` files
+- a small initial prompt/eval set
+- review outputs the user can inspect
+- clear next-step changes when another iteration is required
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/platform-formats.md` | You need deployment or compatibility rules for Claude Code, Codex, Copilot, or Gemini conversion. |
+| `references/schemas.md` | You need the JSON structure for evals, grading artifacts, or review payloads. |
+
+## Scripts
+
+Use the existing tooling instead of re-inventing the loop:
+
+- `scripts/run_eval.py` for the original Claude-oriented eval pass
+- `scripts/run_loop.py` for iterative improvement on the original eval path
+- `scripts/run_eval_universal.py` for the cross-platform eval path
+- `scripts/run_loop_universal.py` for the portable iterative loop
+- `scripts/aggregate_benchmark.py` to summarize quantitative benchmark results
+- `eval-viewer/generate_review.py` to generate a reviewable output bundle for the user
+- `scripts/package_skill.py` when the skill is ready to distribute
+- `scripts/platform_adapter.py` when Gemini conversion or cross-platform deployment is required
+
+## Examples
+
+- "Create a skill for reviewing Flutter Riverpod code and set up a first batch of eval prompts."
+- "Repair this skill package, rerun the viewer, and help me interpret the benchmark regressions."
+- "Turn this prompt workflow into a reusable skill and iterate until the user-approved eval set passes."
+````

package/workflows/powers/skill-creator/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: skill-creator
+description: Create, test, improve, and package portable AI skills using the Agent Skills SKILL.md format across Claude Code, Codex, and GitHub Copilot, with Gemini conversion when needed. Use this when the user wants to build, repair, benchmark, or iterate on a reusable skill package.
+license: Apache-2.0
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Skill Creator
+
+## Purpose
+
+Create and improve reusable AI skill packages with a human-in-the-loop loop: define the skill, draft it, test it with the skill enabled, evaluate results qualitatively and quantitatively, rewrite based on signal, and repeat until the package is good enough to scale.
+
+## When to Use
+
+- The user wants to create a new skill package under `workflows/skills/<name>`.
+- The user wants to repair or modernize an existing `SKILL.md` package.
+- The user wants evals, benchmarks, or review tooling for a skill package.
+- The user wants to package one canonical skill for Claude Code, Codex, GitHub Copilot, and optionally Gemini.
+
+## Instructions
+
+1. Decide what the skill should do before writing files. Confirm the task boundary, activation phrases, expected outputs, supported platforms, and whether the skill needs objective evals.
+
+2. Write a first draft of the skill package. Keep one canonical `SKILL.md` as the source of truth. Add sidecars only when they reduce prompt bloat or remove repeated work.
+
+3. Create a small test set first. Add a few realistic prompts to `evals/` and keep them representative of the skill's actual use cases, not just ideal happy paths.
+
+4. Run the skill with the skill enabled on the test prompts. Prefer Claude with access to the skill for the first qualitative pass so you can inspect whether the instructions actually trigger the right behavior.
+
+5. While runs are happening, draft or refine the quantitative evals. If quantitative evals already exist, review them, keep the ones that are still useful, and adjust only the ones that no longer match the intended behavior.
+
+6. Explain the evals to the user before over-optimizing against them. The user should understand what each prompt, assertion, or benchmark is measuring and what a pass or fail means.
+
+7. Review the outputs both qualitatively and quantitatively. Use `eval-viewer/generate_review.py` so the user can inspect side-by-side outputs and benchmark summaries instead of relying only on raw JSON.
+
+8. Rewrite the skill based on user feedback and the strongest benchmark signal. Fix root causes, not just individual failing prompts, and treat obvious flaws in the quantitative results as design feedback for the skill.
+
+9. Repeat the loop until the results are stable enough. Keep iterating until the user is satisfied or the skill behavior has clearly plateaued.
+
+10. Expand the test set and rerun at larger scale only after the small-set loop is working. Do not scale weak evals or unclear instructions.
+
+11. Use the right script for the job:
+    - `scripts/run_loop.py` is the original Claude-oriented optimization loop built on `run_eval.py`.
+    - `scripts/run_loop_universal.py` is the portable loop built on `run_eval_universal.py` and `platform_adapter.py`.
+    - Prefer the universal loop when the package is intended to stay portable across Claude Code, Codex, Copilot, and Gemini-style workflows.
+
+## Output Format
+
+Produce a canonical skill package with:
+
+- a valid root `SKILL.md`
+- any needed `references/`, `scripts/`, `assets/`, `evals/`, and `eval-viewer/` files
+- a small initial prompt/eval set
+- review outputs the user can inspect
+- clear next-step changes when another iteration is required
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/platform-formats.md` | You need deployment or compatibility rules for Claude Code, Codex, Copilot, or Gemini conversion. |
+| `references/schemas.md` | You need the JSON structure for evals, grading artifacts, or review payloads. |
+
+## Scripts
+
+Use the existing tooling instead of re-inventing the loop:
+
+- `scripts/run_eval.py` for the original Claude-oriented eval pass
+- `scripts/run_loop.py` for iterative improvement on the original eval path
+- `scripts/run_eval_universal.py` for the cross-platform eval path
+- `scripts/run_loop_universal.py` for the portable iterative loop
+- `scripts/aggregate_benchmark.py` to summarize quantitative benchmark results
+- `eval-viewer/generate_review.py` to generate a reviewable output bundle for the user
+- `scripts/package_skill.py` when the skill is ready to distribute
+- `scripts/platform_adapter.py` when Gemini conversion or cross-platform deployment is required
+
+## Examples
+
+- "Create a skill for reviewing Flutter Riverpod code and set up a first batch of eval prompts."
+- "Repair this skill package, rerun the viewer, and help me interpret the benchmark regressions."
+- "Turn this prompt workflow into a reusable skill and iterate until the user-approved eval set passes."

package/workflows/powers/skill-creator/references/platform-formats.md

@@ -0,0 +1,181 @@
+# Platform Format Reference
+
+Detailed file format specifications for each supported platform.
+
+---
+
+## Claude Code — SKILL.md
+
+**Location:** `~/.claude/skills/<skill-name>/SKILL.md`
+**Install:** `npx skills add <repo> --skill <name>`
+**Trigger:** Description-based; Claude reads description and decides whether to load the full skill
+
+```
+---
+name: my-skill
+description: One paragraph. Include what it does AND when to trigger. Be explicit.
+compatibility:
+  tools: [bash, python]   # optional
+---
+
+# Skill Title
+
+Body instructions here. Imperative form. Explain the why.
+
+## When to Use
+## Instructions
+## Output Format
+## Examples
+```
+
+**Tips:**
+- Keep SKILL.md under 500 lines
+- Put large docs in `references/` and point to them from SKILL.md
+- Scripts in `scripts/` can run without being loaded into context
+- Description is the #1 trigger — write it to be "pushy"
+
+---
+
+## OpenAI Codex — AGENTS.md
+
+**Location:** Repo root (`AGENTS.md`) or `.codex/instructions.md`
+**Auto-detection:** Codex looks for `AGENTS.md` at the working directory root
+**Trigger:** Loaded at session start; always active for that session
+
+```markdown
+# Agent Instructions: [Skill Name]
+
+## Purpose
+Brief description of what this agent configuration enables.
+
+## Behavior Rules
+Numbered or bulleted rules. Always include the reason behind each rule.
+
+- Always X because Y
+- When you see Z, do W (reason: ...)
+
+## Output Format
+Describe the expected structure of outputs.
+Specify file names, formats, encodings where relevant.
+
+## Limitations
+What this agent should NOT do.
+What to do if the user asks for something outside scope.
+
+## References
+- See `docs/style-guide.md` for formatting rules
+- See `schemas/output.json` for output structure
+```
+
+**Tips:**
+- Codex respects Markdown headers as logical sections
+- Reference other files with relative paths — Codex can read them
+- Keep the main file focused; delegate detail to referenced docs
+- Subagent spawning is native in Codex
+
+---
+
+## GitHub Copilot — copilot-instructions.md
+
+**Location:** `.github/copilot-instructions.md`
+**Scope:** Workspace-scoped; applies to all Copilot interactions in the repo
+**Trigger:** Always active — no triggering needed or possible
+
+```markdown
+# GitHub Copilot Instructions
+
+## [Skill/Topic Name]
+
+When working on [context/file type/task], follow these rules:
+
+1. [Rule with brief reason]
+2. [Rule with brief reason]
+
+### Output Format
+[Description of expected output structure]
+
+### Avoid
+- [Anti-pattern 1]
+- [Anti-pattern 2]
+
+## [Another Topic]
+...
+```
+
+**Tips:**
+- Instructions are always active — don't make them too restrictive globally
+- Use H2 sections to scope rules to specific contexts
+- Keep total file under ~1000 tokens for reliability
+- No dynamic loading; no scripts; just persistent context
+- Works in VS Code, JetBrains, GitHub.com, and Copilot Chat
+
+---
+
+## Google Gemini Code Assist / Project IDX — GEMINI.md
+
+**Location:** `GEMINI.md` (project root) or `.idx/airules.md`
+**Enterprise:** `codeassist.yaml` for org-wide rules (Google Cloud)
+**Trigger:** Loaded at session start; always active for the project
+
+```markdown
+# Gemini Code Assist Rules: [Skill Name]
+
+## When These Rules Apply
+[Describe the context: specific file types, tasks, user phrases]
+
+## Instructions
+[Steps with reasoning. Imperative form.]
+
+## Expected Output
+[Format, file types, naming conventions]
+
+## Do Not
+[Explicit exclusions]
+```
+
+**For Project IDX — .idx/dev.nix:**
+```nix
+{ pkgs, ... }: {
+  packages = [ pkgs.python311 pkgs.nodejs ];
+  
+  idx.extensions = [
+    "ms-python.python"
+    "esbenp.prettier-vscode"
+  ];
+
+  idx.workspace.onCreate = {
+    npm-install = "npm install";
+  };
+
+  idx.previews = {
+    enable = true;
+    previews = {
+      web = {
+        command = ["npm" "run" "dev"];
+        manager = "web";
+      };
+    };
+  };
+}
+```
+
+**Tips:**
+- `GEMINI.md` is read at session start — keep it concise
+- Project IDX uses Nix for reproducible environments; document dependencies clearly
+- Gemini Code Assist in Google Cloud Workstations supports org-level `codeassist.yaml`
+- IDX AI rules are per-project; no global skill loading
+
+---
+
+## Cross-Platform Conversion Cheatsheet
+
+| Concept | Claude Code | Codex | Copilot | Gemini/IDX |
+|---|---|---|---|---|
+| Main file | `SKILL.md` | `AGENTS.md` | `.github/copilot-instructions.md` | `GEMINI.md` |
+| Trigger | Description field | Session start | Always active | Session start |
+| Scripts | `scripts/` folder | Reference in AGENTS.md | Not supported | Not supported |
+| References | `references/` folder | Relative file paths | Not supported | Not supported |
+| Dynamic loading | Yes | Partial | No | No |
+| Subagents | Via skill system | Native | No | No |
+| Env config | N/A | `.codex/` | N/A | `.idx/dev.nix` |
+